The location directive within NGINX server block allows to route request to correct location within the file system. The directive is used to tell NGINX where to look for a resource by including files and folders while matching a location block against an URL. In this tutorial, we will look at NGINX location directives in details.

General record of Nginx Location directive

The NGINX location block can be placed inside a server block or inside another location block with some restrictions. The syntax for constructing a location block is:

Syntax:    location [ = | ~ | ~* | ^~ ] uri { ... } 
           location @name { ... }
Default:   ---
— 
Context:   server, location

or in simple form:

location [modifier] [URI] {
  ...
  ...
}

The modifier in the location block is optional. Having a modifier in the location block will allow NGINX to treat a URL differently. Few most common modifiers are:

• none - If no modifiers are present in a location block then the requested URI will be matched against the beginning of the requested URI.
• = - The equal sign is used to match a location block exactly against a requested URI.
• ~ - The tilde sign is used for case-sensitive regular expression match against a requested URI.
• ~* - The tilde followed by asterisk sign is used for case insensitive regular expression match against a requested URI.
• ^~ - The carat followed by tilde sign is used to perform longest nonregular expression match against the requested URI. If the requested URI hits such a location block, no further matching will takes place.

The matching is performed against a normalized URI, after decoding the text encoded in the "%XX" form, resolving references to relative path components "." and "..", and possible compression of two or more adjacent slashes into a single slash.

Location can either be defined by a prefix string, or by a regular expression. Regular expressions are specified with the preceding ~* modifier (for case-insensitive matching), or the ~ modifier (for case-sensitive matching).

To find location matching a given request, nginx first checks locations defined using the prefix strings (prefix locations). Among them, the location with the longest matching prefix is selected and remembered. Then regular expressions are checked, in the order of their appearance in the configuration file. The search of regular expressions terminates on the first match, and the corresponding configuration is used. If no match with a regular expression is found then the configuration of the prefix location remembered earlier is used.

Nginx Location directive priority and selection algorithm

• nginx first checks locations defined using the prefix strings
• location directives with the = prefix that match the query exactly. If found, searching stops.
• All remaining directives with prefix strings. If this match used the ^~ prefix, searching stops.
• location with the longest matching prefix is selected and remembered
• then regular expressions are checked, in the order of their appearance in the configuration file
• search of regular expressions terminates on the first match, and the corresponding configuration is used
• if no match with a regular expression is found then the configuration of the prefix location remembered earlier is used

Another definition:

1. Test the URI against all prefix strings.
2. The = (equals sign) modifier defines an exact match of the URI and a prefix string. If the exact match is found, the search stops.
3. If the ^~ (caret-tilde) modifier prepends the longest matching prefix string, the regular expressions are not checked.
4. Store the longest matching prefix string.
5. Test the URI against regular expressions.
6. Break on the first matching regular expression and use the corresponding location.
7. If no regular expression matches, use the location corresponding to the stored prefix string.

Example:

location  = / {
  # matches the query / only.
  [ configuration A ] 
}
location  / {
  # matches any query, since all queries begin with /, but regular
  # expressions and any longer conventional blocks will be
  # matched first.
  [ configuration B ] 
}
location /documents/ {
  # matches any query beginning with /documents/ and continues searching,
  # so regular expressions will be checked. This will be matched only if
  # regular expressions don't find a match.
  [ configuration C ] 
}
location ^~ /images/ {
  # matches any query beginning with /images/ and halts searching,
  # so regular expressions will not be checked.
  [ configuration D ] 
}
location ~* \.(gif|jpg|jpeg)$ {
  # matches any request ending in gif, jpg, or jpeg. However, all
  # requests to the /images/ directory will be handled by
  # Configuration D.   
  [ configuration E ] 
}