Preferential prefix match (^~) in Nginx - Step-by-Step Execution

Process Flow - Preferential prefix match (^~)

Request URL arrives

↓

Check for exact match

↓

Check for ^~ prefix matches

↓

If ^~ prefix match found

↓

Use this location block

↓

If no ^~ prefix match

↓

Check regex locations

↓

Use best matching location

Nginx checks if the request URL matches any location with ^~ prefix first. If yes, it uses that location immediately, skipping regex checks.

Execution Sample

Nginx

location ^~ /images/ {
    # serve images
}

location ~* \.(gif|jpg|jpeg)$ {
    # regex match for images
}

This config prefers the prefix /images/ over regex matches for image files.

Process Table

Step	Request URL	Check	Match Found?	Action Taken
1	/images/logo.jpg	Exact match locations	No	Continue
2	/images/logo.jpg	^~ prefix locations	Yes (/images/)	Use /images/ location, skip regex
3	/images/logo.jpg	Regex locations	Skipped	Skipped due to ^~ match
4	/images/logo.jpg	Serve content	N/A	Content served from /images/ location
5	/pics/photo.gif	Exact match locations	No	Continue
6	/pics/photo.gif	^~ prefix locations	No	Continue
7	/pics/photo.gif	Regex locations	Yes (\.(gif|jpg|jpeg)$)	Use regex location
8	/pics/photo.gif	Serve content	N/A	Content served from regex location
9	/docs/readme.txt	Exact match locations	No	Continue
10	/docs/readme.txt	^~ prefix locations	No	Continue
11	/docs/readme.txt	Regex locations	No	Use default location or 404

💡 Execution stops when a matching location is found or all checks fail.

Status Tracker

Variable	Start	After Step 2	After Step 7	After Step 11
Matched Location	None	/images/	/\.(gif|jpg|jpeg)$/	None
Regex Checked	No	No (skipped)	Yes	Yes
Content Served From	None	/images/ location	Regex location	Default or 404

Key Moments - 3 Insights

Why does nginx skip regex checks when a ^~ prefix match is found?

Because ^~ means 'prefer this prefix match and do not check regex'. See execution_table row 2 where regex is skipped after ^~ match.

What happens if no ^~ prefix match is found?

Nginx continues to check regex locations and then default locations. See execution_table rows 6-11 for this flow.

Does ^~ match require the full URL to match the prefix?

No, it matches if the URL starts with the prefix. For example, /images/logo.jpg matches ^~ /images/ prefix (row 2).

Visual Quiz - 3 Questions

Look at the execution_table, at which step does nginx decide to skip regex checks due to ^~ prefix match?

A Step 2

B Step 3

C Step 6

D Step 7

💡 Hint

Check the 'Match Found?' and 'Action Taken' columns at step 2 and 3.

According to variable_tracker, what is the matched location after step 7 for /pics/photo.gif?

A /images/

B /\.(gif|jpg|jpeg)$/

C None

D Default location

💡 Hint

Look at 'Matched Location' value after step 7 in variable_tracker.

If the URL is /docs/readme.txt, which location does nginx use according to execution_table?

A /images/ location

B Regex location

C Default location or 404

D ^~ prefix location

💡 Hint

Check steps 9-11 in execution_table for /docs/readme.txt.

Concept Snapshot

Nginx location matching order:
1. Exact match
2. ^~ prefix match (prefer this, skip regex)
3. Regex match
4. Default location
^~ means: if URL starts with prefix, use this location immediately.
Regex locations are skipped if ^~ prefix matches.

Full Transcript

When nginx receives a request URL, it first checks for exact location matches. If none found, it looks for any location blocks with the ^~ prefix that match the start of the URL. If a ^~ prefix match is found, nginx immediately uses that location and skips checking regex locations. If no ^~ prefix matches, nginx then checks regex locations. Finally, if no matches are found, nginx uses the default location or returns a 404. This behavior ensures that ^~ prefix matches have priority over regex matches, making prefix matching faster and more predictable.