How to Use Apache .htaccess Rewrite Rules

In this tutorial, you'll learn about How to Use Apache .htaccess Rewrite Rules. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

The Problem

You need to redirect URLs, rewrite clean paths, or block specific requests in Apache. The .htaccess file gives you per-directory control without editing the main server config.

Quick Fix

Step 1: Enable mod_rewrite

sudo a2enmod rewrite
sudo systemctl restart apache2

The rewrite engine must be enabled before any RewriteRule works. Without this step, .htaccess rewrite directives are silently ignored.

Step 2: Basic .htaccess rewrite

RewriteEngine On
RewriteRule ^old-page$ /new-page [R=301,L]

Place this in the web root (usually /var/www/html/.htaccess). R=301 sends a permanent redirect. L stops processing further rules.

Step 3: Remove .php extension

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^([^.]+)$ $1.php [L]

This lets users visit /about and Apache serves /about.php. The RewriteCond checks that the request does not match an existing file.

Step 4: Redirect entire directory

RewriteEngine On
RewriteRule ^blog/(.*)$ /articles/$1 [R=301,L]

A request to /blog/post-title redirects to /articles/post-title. The $1 captures everything after blog/.

Step 5: Force HTTPS

RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^ https://%{HTTP_HOST}%{REQUEST_URI} [R=301,L]

This redirects all HTTP traffic to HTTPS while preserving the hostname and path.

Step 6: Block specific IPs or user agents

RewriteEngine On
RewriteCond %{REMOTE_ADDR} ^192\.168\.1\.100$
RewriteRule ^ - [F]

The [F] flag returns a 403 Forbidden. Use this to block known bad actors or internal-only paths.

Step 7: Test the configuration

curl -I http://localhost/old-page

Expected:

HTTP/1.1 301 Moved Permanently
Location: http://localhost/new-page

Step 8: Verify syntax

sudo apachectl configtest

Expected:

Syntax OK

Alternative Solutions

Put rewrite rules in the virtual host config instead of .htaccess for better performance — Apache reads .htaccess on every request.

Common Errors

RewriteRule not working: AllowOverride must include FileInfo in the Apache config: <Directory /var/www/html> AllowOverride All</Directory>. Without this, .htaccess is ignored.

500 Internal Server Error: A syntax error in .htaccess causes a 500 error. Check the Apache error log at /var/log/apache2/error.log for the exact line.

Infinite redirect loop: A RewriteRule that redirects to itself causes a loop. Add conditions (RewriteCond) to check the URL before applying the rule.

Rewrite not matching query strings: By default, RewriteRule matches the path only, not the query string. Use %{QUERY_STRING} in RewriteCond to match query parameters.

Mod_rewrite not enabled: Even with AllowOverride All, rewrite rules are ignored if mod_rewrite is not loaded. Verify with apachectl -M | grep rewrite.

Performance impact of .htaccess: Apache reads .htaccess on every request in that directory and all parent directories. For high-traffic sites, move rewrite rules to the vhost config for better performance.

Prevention

• Keep .htaccess files out of Git — add them to .gitignore or deploy via CI.
• Use server-level <Directory> blocks in vhost config for faster execution.
• Test each rule with curl -I before deploying to production.
• Document complex regex patterns so teammates can maintain them.