What is nginx's location matching priority order?

First an exact (=) match wins immediately. Otherwise nginx finds the longest matching plain prefix; if that prefix used ^~ it is selected and regexes are skipped. Otherwise regex locations (~ and ~*) are tried in file order and the first match wins. If no regex matches, the longest plain prefix found earlier is used.

What does the ^~ modifier do?

^~ marks a prefix location as preferential. If it is the longest matching prefix, nginx selects it and does not evaluate any regular-expression locations at all. It is the standard way to serve a directory like /static/ without regex blocks intercepting the request.

Are regex locations tried in priority order or file order?

File order. Among regular-expression locations (~ for case-sensitive, ~* for case-insensitive), nginx tries them top to bottom in the configuration and uses the first one that matches. Length does not matter for regexes, so ordering in the file is significant.

How does the longest-prefix rule work?

For plain prefix locations nginx remembers the longest one whose prefix matches the start of the URI. So with /docs/ and /docs/api/ both matching /docs/api/page, the longer /docs/api/ wins. This is independent of where the blocks appear in the file.

Does a trailing slash in a location matter?

Yes for prefix matching length. location /images and location /images/ are different prefixes; /imagesfoo matches the former but not the latter. Choose the trailing slash deliberately when you want to scope a match to a directory rather than a name prefix.

Common nginx Location Block Patterns

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

What location matching decides

When a request arrives, nginx must choose exactly one location block to handle it. The rules are not simply “first match wins” or “longest wins” — there is a specific priority order that mixes modifiers (=, ^~, ~, ~*, none), prefix length, and file order for regexes. Misunderstanding this order is the source of countless “why is the wrong block serving my request” bugs.

How it works

nginx resolves a location in this order:

Exact location = /path — if it matches, stop. Highest priority.
Find the longest matching plain prefix (location /path and location ^~ /path). Remember it.
If that longest prefix used ^~, select it and skip all regex.
Otherwise evaluate regex locations (~ case-sensitive, ~* case-insensitive) in file order; the first to match wins.
If no regex matches, fall back to the longest plain prefix from step 2.

So exact beats preferential prefix, which beats regex, which beats an ordinary prefix. The tester below runs this exact algorithm against any path and your set of blocks.

Tips and notes

Use = for hot single URIs like / or /favicon.ico to short-circuit matching. Use ^~ /static/ to protect an asset directory from regex handlers. Remember regexes are tried in the order written, so put more specific regex blocks above general ones. A trailing slash changes the prefix, so location /api and location /api/ match different sets of URIs — pick deliberately.