Location Matching Priority in Nginx: How It Works

Nginx matches location blocks in a specific order: first exact matches with =, then longest prefix matches with ^~, followed by regex matches in order of appearance. The first regex match wins, and if none match, the longest prefix match is used.

Syntax

Nginx uses different types of location modifiers to define matching rules:

• = for exact match
• ^~ for prefix match with higher priority
• ~ and ~* for case-sensitive and case-insensitive regex matches
• No modifier means a standard prefix match

The matching order depends on these modifiers.

nginx

location = /exact {
    # exact match for /exact
}

location ^~ /images/ {
    # prefix match with high priority for /images/
}

location ~* \.(jpg|jpeg|png)$ {
    # case-insensitive regex match for image files
}

location / {
    # standard prefix match
}

Example

This example shows how Nginx chooses the correct location block based on the request URI:

nginx

server {
    listen 80;

    location = / {
        return 200 "Exact match for root URI\n";
    }

    location ^~ /static/ {
        return 200 "Prefix match with ^~ for /static/\n";
    }

    location ~* \.php$ {
        return 200 "Regex match for PHP files\n";
    }

    location / {
        return 200 "Default prefix match\n";
    }
}

Output

Request: /
Response: Exact match for root URI

Request: /static/image.png
Response: Prefix match with ^~ for /static/

Request: /test.php
Response: Regex match for PHP files

Request: /about
Response: Default prefix match

Common Pitfalls

Common mistakes include:

• Placing regex location blocks before prefix matches without ^~, causing unexpected regex matching.
• Using = for non-exact matches, which will never match.
• Not ordering regex locations properly, since the first regex match wins.

Always use ^~ to prioritize prefix matches over regex.

nginx

location ~ \.php$ {
    # regex match for PHP files
}

location /static/ {
    # standard prefix match
}

# This causes regex to match before prefix, which may be unintended

# Correct way:
location ^~ /static/ {
    # prefix match with priority
}

location ~ \.php$ {
    # regex match
}

Quick Reference

Match Type	Modifier	Description	Priority Order
Exact match	= /uri	Matches the exact URI only	1 (highest)
Prefix match with priority	^~ /prefix/	Matches URIs starting with prefix, skips regex	2
Regex match (case-sensitive)	~ pattern	Matches URIs by regex, case-sensitive	3 (first regex match wins)
Regex match (case-insensitive)	~* pattern	Matches URIs by regex, case-insensitive	3 (first regex match wins)
Standard prefix match	/prefix/	Matches URIs starting with prefix	4 (lowest)

Key Takeaways

Nginx matches locations in this order: exact (=), prefix with ^~, regex (~ or ~*), then standard prefix.

Use = for exact URI matches and ^~ to prioritize prefix matches over regex.

Regex locations are checked in order and the first match is used.

If no regex matches, the longest prefix match is selected.

Ordering and modifiers are key to controlling location matching behavior.