NGINX Rewrite Rules

nginx rewrite

The two main directives used to rewrite in Nginx are the return and rewrite directives, both of which will be explained in this article. Nginx rewrite rules can be defined within your Nginx configuration file in order to change at least part or all of a URL. Usually, this is done for one of two purposes.

  • First, if a URL has changed, using a rewrite rule will let the client know that the resource requested is in a different location. Additionally, if the client makes a common misspelling of the domain name, return and rewrite directives can also be used to help rectify this issue and point the client to the correct URL.
  • Second, rewrite rules can also be used to control the request within Nginx. For example, a request can be forwarded to an application if the content will be generated dynamically.

The Nginx return Directive Explained

The Nginx return directive is the simpler directive to use compared to Nginx rewrite. To use the return directive, it must be enclosed within a server or location block which defines which URLs should be rewritten. The directive should then define the rule which will rewrite the requested URL and return the correct URL.

An example of the return directive being used within a server block may look similar to the following:

server {
 listen 80;
 return 301 $scheme://$request_uri;

In the above example, the old website address would correspond to the client requested URL. The return directive would then return a 301 status code to the browser and redirect the client to the new website address. the Nginx variable $scheme is used to define the protocol (http or https) while $request_uri is for the full URI.

The Nginx rewrite Directive Explained

Similar to the return directive, the Nginx rewrite directive needs to be in a location or server block in order to rewrite the URL. Other than that similarity, both directives are rather different from one another. This directive can be used to perform more granular tasks as with it you can perform more complicated URL distinctions such as:

  • Capture elements in the original URL
  • Change or add elements in the path

The Nginx rewrite directive is in some cases more complicated. The basic syntax looks like this:

rewrite regex URL [flag];

The Nginx rewrite directive does not send a redirect to the client in all cases. If the rewritten URL matches with another following directive, Nginx will rewrite the URL again. A rewrite directive will only return a HTTP 301 or 302 status code. If another status code is required, a return directive is needed after the rewrite directive. For an example of a rewrite directive being used in conjunction with the return directive let’s take a look at an example from Nginx’s rewrite module documentation.

server {
 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last;
 return 403;

In the above scenario, all URLs that begin with /download and then later include /media or /audio are matched. It then replaces the /media or /audio elements with /mp3 and adds the .mp3 or .ra file extension. The return directive specifies that if the URL does not match the rewrite rules then return a 403 back to the client.

For some additional Nginx rewrite / return examples, take a look through the following cases.

if ($http_user_agent ~ MSIE) {
    rewrite ^(.*)$ /msie/$1 break;

if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
    set $id $1;

if ($request_method = POST) {
    return 405;

if ($invalid_referer) {
    return 403;

Leave A Comment?