Location matching priority order in Nginx - Step-by-Step Execution

Process Flow - Location matching priority order

Request URL arrives

↓

Check exact match (=)

↓

Use exact location

No↓

Check prefix match (^~)

↓

Use prefix location

No↓

Check regex matches (~ or ~*)

↓

Use first regex match

No↓

Use longest prefix match

↓

Serve request with matched location

Nginx checks locations in this order: exact match first, then prefix with ^~, then regex, and finally longest prefix match.

Execution Sample

Nginx

location = /exact {
  # exact match block
}

location ^~ /images/ {
  # prefix match block
}

location ~* \.jpg$ {
  # regex match block
}

location / {
  # default prefix match
}

This config shows different location blocks with exact, prefix, regex, and default prefix matches.

Process Table

Step	Check Type	Condition	Result	Action Taken
1	Exact match (=)	Does request URL exactly match /exact?	No	Continue to next check
2	Exact match (=)	Does request URL exactly match /exact?	Yes	Use exact location block
3	Prefix match (^~)	Does request URL start with /images/?	Yes	Use prefix location block
4	Regex match (~ or ~*)	Does request URL match regex \.jpg$?	Yes	Use regex location block
5	Longest prefix match	No exact, ^~, or regex match found	Yes	Use longest prefix location block
6	Exit	Request served with matched location	N/A	Stop checking

💡 Execution stops when a matching location is found or after longest prefix match is used.

Status Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	Final
matched_location	none	none	/exact (if matched)	none or /images/ (if matched)	none or regex match	final matched location

Key Moments - 3 Insights

Why does nginx check exact match locations before prefix or regex?

Because exact matches (=) have the highest priority and stop further checks immediately, as shown in execution_table step 2.

What happens if a prefix match with ^~ is found?

Nginx uses that prefix location immediately without checking regex locations, as shown in execution_table step 3.

When does nginx use regex location blocks?

Only if no exact or ^~ prefix matches are found, nginx tests regex locations in order and uses the first match, as shown in execution_table step 4.

Visual Quiz - 3 Questions

Look at the execution table, at which step does nginx stop checking if an exact match is found?

A Step 1

B Step 3

C Step 2

D Step 5

💡 Hint

Check the 'Action Taken' column at step 2 in the execution_table.

If a request URL starts with /images/ but also matches a regex, which location block does nginx use?

A Prefix location block with ^~

B Exact match location block

C Regex location block

D Longest prefix match location

💡 Hint

Refer to execution_table step 3 where prefix ^~ match takes priority over regex.

According to variable_tracker, what is the value of matched_location after step 4 if no exact or ^~ prefix matches were found but regex matched?

A /exact

B regex match location

C none

D longest prefix location

💡 Hint

Look at the 'matched_location' row in variable_tracker after step 4.

Concept Snapshot

Nginx location matching order:
1. Exact match (=) has highest priority.
2. Prefix match with ^~ stops regex checks.
3. Regex (~ or ~*) matches next.
4. Longest prefix match used last.
Request served by first matched location.

Full Transcript

Nginx processes incoming requests by checking location blocks in a specific order. First, it looks for an exact match using '='. If found, it immediately uses that location. If not, it checks for prefix matches marked with '^~', which also stop further regex checks if matched. If neither exact nor ^~ prefix matches are found, nginx tests regex locations in order and uses the first regex match. If no regex matches, nginx falls back to the longest prefix match. This priority ensures efficient and predictable request routing.

Practice

1. Which type of location block does nginx check first when matching a request URL?

easy

A. Prefix match without any modifier

B. Exact match using = modifier

C. Regular expression match using ~ or ~*

D. Prefix match with ^~ modifier

Solution

1. Step 1: Understand nginx location matching order

   nginx first looks for an exact match location block marked with =.

2. Step 2: Confirm priority of exact match

   If an exact match is found, nginx immediately uses it without checking other blocks.

3. Final Answer:

   Exact match using = modifier -> Option B

4. Quick Check:

   Exact match = first checked [OK]

Hint: Exact match with = is always checked first [OK]

Common Mistakes:

• Thinking prefix matches are checked before exact matches
• Confusing ^~ modifier priority
• Assuming regex matches are checked first

2. Which of the following is the correct syntax for a location block that uses a case-insensitive regular expression match?

easy

A. location ~ "/images/" { }

B. location ^~ "/images/" { }

C. location = "/images/" { }

D. location ~* "/images/" { }

Solution

1. Step 1: Identify regex modifiers in nginx

   Modifier ~* means case-insensitive regex match.

2. Step 2: Match syntax to case-insensitive regex

   location ~* "/images/" { } uses ~* correctly for case-insensitive regex.

3. Final Answer:

   location ~* "/images/" { } -> Option D

4. Quick Check:

   ~* = case-insensitive regex [OK]

Hint: Use ~* for case-insensitive regex location [OK]

Common Mistakes:

• Using ~ instead of ~* for case-insensitive match
• Confusing ^~ with regex modifiers
• Using = for regex match

3. Given this nginx config snippet, which location block will handle the request for URL /images/logo.png?

location = /images/logo.png { return 200 'Exact match'; }
location ^~ /images/ { return 200 'Prefix ^~ match'; }
location ~* \.(png|jpg)$ { return 200 'Regex match'; }
location / { return 200 'Default prefix match'; }

medium

A. Exact match location = /images/logo.png

B. Prefix match location ^~ /images/

C. Regex match location ~* \.(png|jpg)$

D. Default prefix match location /

Solution

1. Step 1: Check for exact match

   Request URL is /images/logo.png, which exactly matches = /images/logo.png.

2. Step 2: Confirm nginx uses exact match first

   nginx uses exact match location immediately without checking others.

3. Final Answer:

   Exact match location = /images/logo.png -> Option A

4. Quick Check:

   Exact match wins over prefix and regex [OK]

Hint: Exact match location = always wins first [OK]

Common Mistakes:

• Choosing ^~ prefix match over exact match
• Assuming regex match has higher priority
• Ignoring exact match syntax

4. You have this nginx config:

location /images/ {
  return 200 'Prefix match';
}
location ^~ /images/ {
  return 200 'Prefix ^~ match';
}

But requests to /images/photo.jpg return 'Prefix match' instead of 'Prefix ^~ match'. What is the likely cause?

medium

A. Two prefix locations with same path cause nginx to pick first declared

B. ^~ modifier is ignored if regex location exists

C. Regex location always has higher priority than ^~

D. Syntax error in ^~ location block

Solution

1. Step 1: Understand prefix location conflicts

   Two prefix locations with identical paths cause nginx to use the first declared one.

2. Step 2: Check config order

   The location /images/ block appears before location ^~ /images/, so nginx picks the first.

3. Final Answer:

   Two prefix locations with same path cause nginx to pick first declared -> Option A

4. Quick Check:

   First prefix wins if paths identical [OK]

Hint: Avoid duplicate prefix locations; nginx picks first declared [OK]

Common Mistakes:

• Assuming ^~ always overrides prefix regardless of order
• Thinking regex always beats ^~
• Believing syntax error causes this behavior

5. You want nginx to serve static files under /static/ using a prefix match but avoid regex checks for these URLs for performance. Which configuration achieves this best?

hard

A. location /static/ { root /var/www/static; }

B. location ~* /static/ { root /var/www/static; }

C. location ^~ /static/ { root /var/www/static; }

D. location = /static/ { root /var/www/static; }

Solution

1. Step 1: Understand ^~ modifier effect

   Using ^~ tells nginx to stop searching regex locations if this prefix matches.

2. Step 2: Apply to static files

   Setting location ^~ /static/ ensures static files served quickly without regex overhead.

3. Final Answer:

   location ^~ /static/ { root /var/www/static; } -> Option C

4. Quick Check:

   ^~ prefix disables regex checks [OK]

Hint: Use ^~ prefix to skip regex for performance [OK]

Common Mistakes:

• Using plain prefix allows regex checks
• Using regex location unnecessarily
• Using exact match = for directory prefix