The RewriteRule directive is the real rewriting workhorse. The directive can occur more than once, with each instance defining a single rewrite rule. The order in which these rules are defined is important - this is the order in which they will be applied at run-time.

Pattern is a perl compatible regular expression. What this pattern is compared against varies depending on where the RewriteRule directive is defined.

What is matched?

• In VirtualHost context, The Pattern will initially be matched against the part of the URL after the hostname and port, and before the query string (e.g. "/app1/index.html"). This is the (%-decoded) URL-path.

• In per-directory context ( Directory and .htaccess), the Pattern is matched against only a partial path, for example a request of "/app1/index.html" may result in comparison against "app1/index.html" or "index.html" depending on where the RewriteRule is defined.

  The directory path where the rule is defined is stripped from the currently mapped filesystem path before comparison (up to and including a trailing slash). The net result of this per-directory prefix stripping is that rules in this context only match against the portion of the currently mapped filesystem path "below" where the rule is defined.

  Directives such as DocumentRoot and Alias , or even the result of previous RewriteRule substitutions, determine the currently mapped filesystem path.

• If you wish to match against the hostname, port, or query string, use a RewriteCond with the %{HTTP_HOST} , %{SERVER_PORT} , or %{QUERY_STRING} variables respectively.

Per-directory Rewrites

• The rewrite engine may be used in .htaccess files and in <Directory> sections, with some additional complexity.
• To enable the rewrite engine in this context, you need to set " RewriteEngine On " and " Options FollowSymLinks " must be enabled. If your administrator has disabled override of FollowSymLinks for a user's directory, then you cannot use the rewrite engine. This restriction is required for security reasons.
• See the RewriteBase directive for more information regarding what prefix will be added back to relative substitutions.
• If you wish to match against the full URL-path in a per-directory (htaccess) RewriteRule, use the %{REQUEST_URI} variable in a RewriteCond .
• The removed prefix always ends with a slash, meaning the matching occurs against a string which never has a leading slash. Therefore, a Pattern with ^/ never matches in per-directory context.
• Although rewrite rules are syntactically permitted in <Location> and <Files> sections (including their regular expression counterparts), this should never be necessary and is unsupported. A likely feature to break in these contexts is relative substitutions.

For some hints on regular expressions, see the mod_rewrite Introduction.

In mod_rewrite, the NOT character (' ! ') is also available as a possible pattern prefix. This enables you to negate a pattern; to say, for instance: if the current URL does NOT match this pattern. This can be used for exceptional cases, where it is easier to match the negative pattern, or as a last default rule.

Note

The Substitution of a rewrite rule is the string that replaces the original URL-path that was matched by Pattern. The Substitution may be a:

file-system path

Designates the location on the file-system of the resource to be delivered to the client. Substitutions are only treated as a file-system path when the rule is configured in server (virtualhost) context and the first component of the path in the substitution exists in the file-system

URL-path

A DocumentRoot -relative path to the resource to be served. Note that mod_rewrite tries to guess whether you have specified a file-system path or a URL-path by checking to see if the first segment of the path exists at the root of the file-system. For example, if you specify a Substitution string of /www/file.html , then this will be treated as a URL-path unless a directory named www exists at the root or your file-system (or, in the case of using rewrites in a .htaccess file, relative to your document root), in which case it will be treated as a file-system path. If you wish other URL-mapping directives (such as Alias ) to be applied to the resulting URL-path, use the [PT] flag as described below.

Absolute URL

If an absolute URL is specified, mod_rewrite checks to see whether the hostname matches the current host. If it does, the scheme and hostname are stripped out and the resulting path is treated as a URL-path. Otherwise, an external redirect is performed for the given URL. To force an external redirect back to the current host, see the [R] flag below.

- (dash)

A dash indicates that no substitution should be performed (the existing path is passed through untouched). This is used when a flag (see below) needs to be applied without changing the path.

In addition to plain text, the Substitution string can include

1. back-references ( $N ) to the RewriteRule pattern
2. back-references ( %N ) to the last matched RewriteCond pattern
3. server-variables as in rule condition test-strings ( %{VARNAME} )
4. mapping-function calls ( ${mapname:key|default} )

Back-references are identifiers of the form $ N (N=0..9), which will be replaced by the contents of the Nth group of the matched Pattern. The server-variables are the same as for the TestString of a RewriteCond directive. The mapping-functions come from the RewriteMap directive and are explained there. These three types of variables are expanded in the order above.

Rewrite rules are applied to the results of previous rewrite rules, in the order in which they are defined in the config file. The URL-path or file-system path (see "What is matched?", above) is completely replaced by the Substitution and the rewriting process continues until all rules have been applied, or it is explicitly terminated by an L flag, or other flag which implies immediate termination, such as END or F .

Modifying the Query String

By default, the query string is passed through unchanged. You can, however, create URLs in the substitution string containing a query string part. Simply use a question mark inside the substitution string to indicate that the following text should be re-injected into the query string. When you want to erase an existing query string, end the substitution string with just a question mark. To combine new and old query strings, use the [QSA] flag.

Additionally you can set special actions to be performed by appending [ flags ] as the third argument to the RewriteRule directive. Flags is a comma-separated list, surround by square brackets, of any of the flags in the following table. More details, and examples, for each flag, are available in the Rewrite Flags document.

Home directory expansion

When the substitution string begins with a string resembling "/~user" (via explicit text or backreferences), mod_rewrite performs home directory expansion independent of the presence or configuration of mod_userdir .

This expansion does not occur when the PT flag is used on the RewriteRule directive.

Here are all possible substitution combinations and their meanings:

Inside per-server configuration ( apache2.conf )
for request GET /somepath/pathinfo:

Inside per-directory configuration for /somepath
( /physical/path/to/somepath/.htaccess , with RewriteBase "/somepath" )
for request GET /somepath/localpath/pathinfo: