URL Rewriting

The URL that a client requests can be changed entirely or patly using the NGINX rewrite rules. In addition to directing the flow of NGINX’s executing pages, the primary goal of updating a URL is to alert the clients that the services they are seeking have moved. URLs are rewritten using the return and rewrite commands in NGINX. The same task of rewriting the URLs is carried out by both directives. The rewrite directive is stronger than the return directive, as it can handle a complicated rewriting without the need to parse the URLs. We will examine in this guide on how the NGINX uses the return and rewrite commands to modify or rewrite the URL.

It is highly advised to update the current Nginx instance to the higher version because this instruction is optimized for NGINX version 1.0.1 and above. Nevertheless, some of the operations and syntaxes might still apply to the versions earlier than the one mentioned.

Return Directive in Ubuntu 20.04

The fundamental and well-understood return command is used to accomplish the URL rewriting. Although it doesn’t employ the regular expressions, it can parse the variables that are taken from the path of the location block. Typically, the return directive is used to reroute the request URL to a different place. As a result, it frequently employs the HTTP status codes like 301 for continuous redirection and 302 for temporary redirection. The examples of the return directive use cases are shown in the following code fragments:

Implementation of Return Directive in Server Setting

When moving your website to a new domain and reroute all of the old URLs to the new domain, the return directive in the server environment comes in quite handy. Making your site to redirect to either the “www” version or the “non-www” version also aids in canonicalizing the URL.

The return directive in the previous server context changes the URL that is intended for the site which is the old domain to the site which is the new domain. When NGINX sees a URL that contains the site, it immediately halts the page processing and provides the client a 301-response code and rebuilts the URL. The $scheme and $request uri are the two variables that are utilized in the return directive. The $request variable uri includes the full URI with any parameters. And the $scheme variable is employed to define the URL scheme (http or https). When rewriting the URL, keep in mind that both variables retrieve this information from the input URL.

Implementation of Return Directive in Location Setting

In some circumstances, forwarding the pages is preferable in dealing with domains. You can reroute the pages to a different location using the return directive found inside the location block.

When a request URL matches exactly the /articles/samples-nginx pattern in the example, NGINX redirects the request to the new address. You can also change the position of everything for a certain path. The following example demonstrates how to redirect any pages that are marked as “/samples” to

Rewrite Directive in Ubuntu 20.04

The web server’s internal ability to rewrite the URLs without disclosing the core method to the client machine is accomplished through the rewrite directive. It uses the regular expressions and conforms to its syntax. The replacement placeholder replaces the matched URL. The regex placeholder allows the regular expressions to be used. And the flag allows the execution flow to be changed. The flags break, permanent, redirect, and last are currently used in rewrite directives.

The syntax details are given in the following:

  • regex: The regular expression built using the PCRE that is applied to the URL of the incoming requests.
  • replacement-url: If the requested URL matches the regular expression, the requested URL is changed using the replacement string.
  • flag: Whether the rewrite command must be processed further depends on the value of the flag.

Note that only the codes 301 or 302 may be returned by the rewrite directive. After the rewrite directive, a return directive must be included explicitly if you want to return any extra codes.

Implementation of Rewrite Directive for Static Page

Take the case where you want to change a page’s URL, such as to In the following location block, a rewrite directive is provided to accomplish the same task.

According to the location command location = /nginx-samples, only the URLs with the exact prefix /nginx-samples match the location block. The requesting URL is examined by NGINX for the “/nginx-samples?$” pattern. The specific meanings of the characters “^”,”?”, and “$” are employed to define the pattern. The string that needs to be matched starts with “^”. The string’s end to be matched is indicated by the “$” symbol. The non-greedy modifier sign is “?”.

Once a match is found, a non-greedy modifier stops looking for patterns. If the requested URI matches the pattern, the “otherpage.html” is substituted. The rewriting also terminates because the rewrite constraint ends with a break. But the modified request is not forwarded to a different location.

Implementation of Rewrite Directive for Dynamic Page

Now, consider a dynamic page where the dynamic part is id=11: (uid). If you use the most recent way of rewriting the URLs, you need 10 rewrite directives for each of your 10 users. Instead, it is feasible to extract the URL components into variables and utilize those variables to create a single rewrite command that handles all the dynamic pages.

With the location command “location = /linux-user”, NGINX is instructed to search the location directive with a URL that has the “/linux-user” prefix in it exactly. NGINX scans the requested URL for the “linux-user/([0-9]+)/?$” pattern. The range of characters in the square bracketed regular expression “^[0-9]+” is between 0 and 9. A matching character or characters are indicated by the “+” symbol. In the absence of the “+” sign, the regular expression identifies just the single characters like 5 or 8, but not 25 or 44. The regular expression’s parentheses() marks the back-reference. This back-reference is shown by the “$1” in the “linux-user.php?id=$1” substitution URL.


The rewrite or return directives can now be used to rewrite the URLs. The rewriting examples given in this course are straightforward to comprehend. As shown in the examples, the return directive is used to inform the browser and the search engine crawlers of the location of the page. While the rewrite directive can be used to abstract away the URL rewriting operation without making the browser aware of what is happening behind the scenes.

About the author

Omar Farooq

Hello Readers, I am Omar and I have been writing technical articles from last decade. You can check out my writing pieces.