Hosting glossarymod_rewrite is an Apache web server module that rewrites requested URLs using rules, often in .htaccess. WordPress uses it for pretty permalinks.
mod_rewrite is the part of the Apache web server that decides what to do with a requested URL before Apache looks for a file. Using pattern-matching rules, it can quietly map a clean address such as /about/ onto the script that builds the page, or send the visitor to a different address with a redirect. Rules usually live in a .htaccess file in the site's folder, or in Apache's main configuration.
How WordPress uses it
When pretty permalinks are on (Settings, then Permalinks, with any structure other than "Plain"), WordPress writes this block to .htaccess:
# BEGIN WordPress
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>
# END WordPress
In plain English: if the request is for a file or folder that really exists, such as an image, serve it; otherwise hand the request to index.php. WordPress then reads the URL itself and works out which post, page, or archive to show. mod_rewrite does not know about posts at all; it just funnels requests to WordPress. The line with HTTP_AUTHORIZATION passes authorization headers through to PHP, which features such as application passwords need.
WordPress rewrites everything between the # BEGIN WordPress and # END WordPress markers when permalinks are saved, so put your own rules above or below that block, never inside it.
Writing rules
RewriteEngine Onswitches rewriting on.RewriteRule pattern substitution [flags]matches the URL path against a regular expression and says what to do instead.RewriteCondadds a condition that must be true for the next rule to apply, for example on the host name, HTTPS status, or query string.
Common flags are [L] (stop processing after this rule), [R=301] (send a permanent redirect rather than rewriting internally), [NC] (case-insensitive), [QSA] (keep the original query string), and [QSD] (discard it). A permanent redirect from an old page:
RewriteRule ^old-page/?$ /new-page/ [R=301,L]
The pattern in a RewriteRule never sees the query string; to match ?ref=x, use a RewriteCond on %{QUERY_STRING}.
The difference between rewriting and redirecting matters. An internal rewrite changes which resource Apache serves while the address bar stays the same. A redirect tells the browser to request a new URL, which it shows. For moved content, a 301 redirect passes full link equity to the new address. For simple one-to-one redirects, Apache's Redirect and RedirectMatch directives are easier to read than mod_rewrite.
Troubleshooting
- Every page except the home page returns 404: mod_rewrite is not enabled, or the server ignores
.htaccess(AllowOverride None). On your own Debian or Ubuntu server,sudo a2enmod rewriteand an Apache restart enable it. On any host, re-saving the permalink settings rewrites a missing or damaged WordPress block. - 500 Internal Server Error right after an edit: a typo in
.htaccess. Restore the backup copy you made before editing, then check Apache's error log for the exact line. - Redirect loops when forcing HTTPS: behind a CDN or load balancer, Apache may see every request as plain HTTP. Check the forwarded protocol header instead of
%{HTTPS}, or force HTTPS at the CDN.
Performance and other servers
Apache reads .htaccess files on every request, so rules in the main server configuration are faster where you have access to it. Keep rule lists short, and put specific patterns before broad ones.
LiteSpeed reads Apache-style rewrite rules, so .htaccess works there too. NGINX does not use .htaccess or mod_rewrite at all; the same jobs are done with try_files, return, and rewrite in its server configuration. Our guide to WordPress permalink structure covers choosing URL formats.