Key facts
- Plain text, one user per line in the form username:hash.
- Hash formats: bcrypt ($2y$), Apache MD5 ($apr1$), SHA-1 ({SHA}) and system crypt(); bcrypt is the recommended choice.
- Referenced by AuthUserFile in Apache config or .htaccess, and by auth_basic_user_file in Nginx.
- Created with the htpasswd utility from apache2-utils (Debian/Ubuntu) or httpd-tools (RHEL/Fedora).
- Usually under 1 KB; should be stored outside the public web root.
How to open a .htpasswd file
Windows
Open it in Notepad or VS Code to view usernames. Manage entries with htpasswd.exe from the bin folder of an Apache for Windows build (e.g. Apache Lounge) or XAMPP.
macOS
View it in TextEdit or Terminal (cat .htpasswd). macOS includes the htpasswd command: htpasswd -B .htpasswd alice adds or updates a user.
Linux
Create a new file with sudo htpasswd -c -B /etc/apache2/.htpasswd alice, and add more users without -c (which would overwrite the file).
Common problems and fixes
- Login prompt keeps reappearing with the right password
- The hash format is unsupported, the file has Windows CRLF line endings, or AuthUserFile points to a different file. Regenerate the entry with htpasswd -B, save with LF endings and use an absolute path.
- 500 Internal Server Error after adding basic auth
- Apache cannot read the file or the directives are invalid in that context. Check the error log, confirm the absolute AuthUserFile path, file permissions and that AllowOverride AuthConfig is enabled.
- Existing users disappeared
- The -c flag was used again, which recreates the file from scratch. Restore from backup and only use -c when creating the first user.
- .htpasswd can be downloaded from the website
- Apache blocks .ht* files by default, but Nginx and misconfigured hosts do not. Move it outside the document root or add a deny rule for it.
Often converted to or from: Nginx auth_basic file (same format), bcrypt hashes from older MD5/SHA entries