Mastering Nginx Location Matching: Rules, Priorities, and Config Examples

Location Matching Symbols

~

: Regular expression match, case‑sensitive ~*: Regular expression match, case‑insensitive ^~: Prefix match; if it matches, stop searching further regular‑expression locations =: Exact match of the request URI @: Named location for internal redirects (e.g., error_page, try_files)

Matching Priority

Exact match ( =) – if found, stop searching.

Prefix match – longest matching prefix; if the prefix uses ^~, stop searching.

Regular‑expression match – evaluated in the order they appear; first match stops the search.

Default match – used when no previous rule matches.

Example Configuration

location = / {
  # Exact match for "/" – no characters after the host name
  [ configuration A ]
}

location / {
  # Matches all requests because every URI starts with "/"
  # Longer prefixes and regexes are evaluated first
  [ configuration B ]
}

location /documents/ {
  # Matches any URI beginning with "/documents/"
  [ configuration C ]
}

location ~ /documents/Abc {
  # Regex match for "/documents/Abc"
  [ configuration CC ]
}

location ^~ /images/ {
  # Prefix match for "/images/" – stops further regex processing
  [ configuration D ]
}

location ~* \.(gif|jpg|jpeg)$ {
  # Regex for image file extensions
  [ configuration E ]
}

location /images/ {
  # Prefix match for "/images/" – continues search, finds ^~ D above
  [ configuration F ]
}

location /images/abc {
  # Longest prefix match for "/images/abc"
  [ configuration G ]
}

location ~ /images/abc/ {
  # Regex match that would be used only if ^~ D were removed
  [ configuration H ]
}

location ~* /js/.*/\.js {
  # Example of a complex regex for JavaScript files
}

Matching Examples

/

→ configuration A (exact match) /downloads/download.html → configuration B /images/1.gif → configuration D (stops at ^~) /images/abc/def → configuration D (longest prefix G matched, then ^~ D stops) /documents/document.html → configuration C /documents/1.jpg → configuration E (regex after C) /documents/Abc.jpg → configuration CC (longest prefix C then regex CC, E is ignored)

Reference: nginx.org – location module documentation