How to write an .htaccess file
An .htaccess file holds Apache settings for one folder and everything below it. It is handy on shared hosting where you cannot edit the main server config. It is also easy to break a whole site with one typo, so this guide pairs each rule with a way to test it.
First check that it applies to you
Only the Apache web server reads .htaccess, and only when the main configuration allows it with AllowOverride. Nginx ignores the file completely, and so do most static hosting platforms, which use their own redirect and header settings. If your rules seem to do nothing, confirm the server software before you debug the rules. A response header such as Server: Apache is a clue, though many servers hide it.
Redirect one page to another
The simplest redirect uses mod_alias, with the old path and the new path:
Redirect 301 /old-pricing.html /plans.html
Redirect 301 /blog/ /articles/
A 301 tells browsers and search engines the move is permanent. Use 302 while you are still testing, because browsers cache 301 responses hard and a mistake can stick in your own browser after you fix the file. The second line moves a whole folder: a request for /blog/post.html goes to /articles/post.html.
Pattern redirects with mod_rewrite
For anything with patterns or conditions, turn on the rewrite engine. Suppose old article addresses looked like /news/2/my-post and now live at /articles/my-post, but only for requests that do not match a real file:
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^news/[0-9]+/(.+)$ /articles/$1 [R=301,L,NC]
RewriteCondlines are tests; the rule below them runs only if they pass.!-fmeans “is not an existing file”.- In
.htaccessthe path the rule sees has no leading slash, which is why the pattern starts withnews/, not/news/. (.+)captures the slug, and$1inserts it into the target.R=301sends a permanent redirect,Lstops processing more rules for this request, andNCignores letter case.
Moving visitors to one host name, such as the www version, or forcing the secure scheme follows the same shape: a condition on %{HTTP_HOST} or %{HTTPS}, then a rule whose target is the full address with %{REQUEST_URI} appended. Many hosts offer both as a switch in their control panel, which is simpler and harder to get wrong.
Custom error pages
ErrorDocument 404 /404.html
ErrorDocument 500 /500.html
Use a local path that starts with a slash. If you give a full address on another host, Apache sends a redirect instead, and the visitor’s browser never sees the real 404 status.
Block access to sensitive files
<FilesMatch "^\.(env|git)">
Require all denied
</FilesMatch>
Options -Indexes
The first block refuses any file whose name starts with .env or .git. Options -Indexes stops Apache from showing a list of files when a folder has no index page. The Require syntax is for Apache 2.4; very old servers used Order and Deny instead. Better still, keep secrets outside the public web folder entirely.
Caching headers
<IfModule mod_expires.c>
ExpiresActive On
ExpiresByType image/webp "access plus 1 month"
ExpiresByType text/css "access plus 1 week"
ExpiresByType text/html "access plus 0 seconds"
</IfModule>
The IfModule wrapper means the block is skipped, rather than crashing the site, if the module is not loaded. Long cache times suit files whose names change when their content changes; keep HTML short so visitors see updates.
Testing without guessing
- Keep a copy of the working file before every edit.
- Change one rule at a time.
- Check the result from a terminal:
curl -I example.com/old-pricing.htmlshould show the status line and aLocationheader. - If the whole site returns a 500 error, the file has a syntax error or uses a module that is not loaded. Restore the copy, then read the server error log.
Questions
Does .htaccess slow a site down?
A little. Apache checks for the file in every folder on the path of each request. If you control the main config, put rules there and turn overrides off.
What permissions should the file have?
644 is typical: the owner can edit it, and the web server can read it. It never needs execute permission.