319

What order do location directives fire in?

user650505
  • 3,791
  • 4
  • 17
  • 7

4 Answers4

485

From the HTTP core module docs:

  1. Directives with the "=" prefix that match the query exactly. If found, searching stops.
  2. All remaining directives with conventional strings. If this match used the "^~" prefix, searching stops.
  3. Regular expressions, in the order they are defined in the configuration file.
  4. If #3 yielded a match, that result is used. Otherwise, the match from #2 is used.

Example from the documentation:

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 ] 
}

If it's still confusing, here's a longer explanation.

Jens
  • 5,767
  • 5
  • 54
  • 69
Martin Redmond
  • 13,366
  • 6
  • 36
  • 32
  • 14
    with it can help you :)https://github.com/detailyang/nginx-location-match-visible – user2228392 Aug 01 '16 at 07:33
  • 11
    Note that both `/` and `/documents/` rules match the request `/documents/index.html`, but the latter rule takes precedence since it's the longest rule. – arrakis_sun Aug 13 '17 at 19:23
  • 1
    Important caveat: `location /test/` will be magically half-used (proxy_pass, add_header etc will be evaluated, but setting variables will not) over `location ~* ^/test$` for requests to `/test` and will return a redirect, only `location = /test` can overrule this. – janh Jun 30 '23 at 09:12
147

It fires in this order.

  1. = (exactly)

    location = /path

  2. ^~ (forward match)

    location ^~ /path

  3. ~ (regular expression case sensitive)

    location ~ /path/

  4. ~* (regular expression case insensitive)

    location ~* .(jpg|png|bmp)

  5. /

    location /path

roens
  • 333
  • 2
  • 9
Don Dilanga
  • 2,722
  • 1
  • 18
  • 20
  • 9
    ^~ (forward match) very important – iwind Jan 21 '20 at 09:46
  • 3
    Leaving off the the trailing slash will match more than just exact. #1 should be `location = /path/`, and the others should include start and end modifiers (`^` and `$`) – Steven Spungin Jun 22 '21 at 17:29
  • location = /path matches to domain.com/path, and location = /path/ to domain.com/path/. Others don't need start and end modifiers. – Don Dilanga Jun 22 '21 at 23:19
  • The regular expressions matchers, case-sensitive and insensitive, have same precedence. Correct this information please. – Niloct Feb 24 '23 at 19:00
49

There is a handy online tool for testing location priority now:
location priority testing online

Iceberg
  • 2,744
  • 19
  • 19
15

Locations are evaluated in this order:

  1. location = /path/file.ext {} Exact match
  2. location ^~ /path/ {} Priority prefix match -> longest first
  3. location ~ /Paths?/ {} (case-sensitive regexp) and location ~* /paths?/ {} (case-insensitive regexp) -> first match
  4. location /path/ {} Prefix match -> longest first

The priority prefix match (number 2) is exactly as the common prefix match (number 4), but has priority over any regexp.

For both prefix matche types the longest match wins.

Case-sensitive and case-insensitive have the same priority. Evaluation stops at the first matching rule.

Documentation says that all prefix rules are evaluated before any regexp, but if one regexp matches then no standard prefix rule is used. That's a little bit confusing and does not change anything for the priority order reported above.

Vincenzo Buttazzo
  • 159
  • 1
  • 4