Mastering Nginx Location: Precise, Regex, and Prefix Matching Explained

Nginx is a high‑performance reverse proxy server used for static proxying, load balancing, rate limiting, and many other scenarios. To use Nginx flexibly, you must understand its configuration files, especially the location directive in the HTTP block.

Overview

The official Nginx documentation defines the location syntax as:

<code>location [=|~|~*|^~] uri { … }</code>

The four optional modifiers inside the brackets change how the request string and URI are matched. uri can be a plain string (standard URI) or a regular expression (regex URI).

Four Optional Modifiers

Examples of the modifiers:

<code>location ~ .*(php|php5)?$ {</code>

When the URI contains a regular expression, you must use ~ (case‑sensitive) or ~* (case‑insensitive). Adding ! before ~ or ~* negates the match:

!~ – case‑sensitive negative regex match.

!~* – case‑insensitive negative regex match.

Exact Match (=)

<code>location = /login {
  # Exact match for /login; stop processing further locations.
}</code>

Case‑Sensitive Regex (~)

<code>location ~ /images/ {
  # Regex match, case‑sensitive; stop after a successful match.
}</code>

Case‑Insensitive Regex (~*)

<code>location ~* /images/ {
  # Regex match, case‑insensitive; stop after a successful match.
}</code>

Prefix Match (^~)

<code>location ^~ /images/ {
  # Prefix match; if matched, regular‑expression locations are ignored.
}</code>

Standard Prefix Match (Longest Prefix)

<code>location /blog/ {
  # Matches any URI starting with /blog/; order does not matter.
}</code>

Location Matching Order

When no modifier is present, Nginx follows these rules:

Search all location blocks in the server context for exact URI matches; if multiple match, choose the most specific.

Evaluate regex locations; the first successful regex stops further processing.

If no regex matches, use the longest standard prefix match.

Additional notes:

Exact matches ( = ) are evaluated first.

Standard prefix matches are order‑independent; the longest match wins.

Regex matches are evaluated in the order they appear.

A catch‑all location location / matches all requests but is overridden by more specific rules.

Combined Matching Priority

The overall priority is:

<code>(location =) > (location exact path) > (location ^~ prefix) > (location ~ and ~* regex) > (location longest prefix) > (location /)</code>

Case Study

Given the following rules:

<code>location = / { echo "Rule A"; }
location = /login { echo "Rule B"; }
location ^~ /blog/ { echo "Rule C"; }
location ~ \.(gif|jpg|png|js|css)$ { echo "Rule D"; }
location ~* \.png$ { echo "Rule E"; }
location / { echo "Rule F"; }
location /blog/detail { echo "Rule G"; }
location /images { echo "Rule Y"; }
location ^~ /static/files { echo "Rule X"; }</code>

Requests resolve as follows:

http://www.example.com/ matches Rule A (exact match).

http://www.example.com/login matches Rule B (exact match).

http://www.example.com/login.html falls back to Rule F (catch‑all).

http://www.example.com/blog/detail/3.html matches Rule C (non‑regex prefix ^~ /blog/ ).