Location matching priority order in Nginx - Commands & Configuration

Introduction

When a web server receives a request, it needs to decide which part of its configuration should handle that request. Nginx uses location blocks to match request URLs, but it follows a specific priority order to choose the best match. Understanding this order helps you control how your server responds to different URLs.

When you want to serve different content based on URL paths, like serving images from one folder and API responses from another.

When you need to redirect certain URLs to other locations or servers.

When you want to apply special rules or settings to specific URL patterns.

When you want to optimize performance by matching exact URLs before more general patterns.

When you want to avoid conflicts between overlapping URL patterns.

Config File - nginx.conf

nginx.conf

server {
    listen 80;
    server_name example.com;

    location = /exact {
        return 200 'Exact match location';
    }

    location /images/ {
        return 200 'Prefix match location for images';
    }

    location ~* \.jpg$ {
        return 200 'Regex match location for jpg files';
    }

    location / {
        return 200 'Default location';
    }
}

This configuration shows different types of location blocks:

• = /exact matches the exact URL /exact.
• /images/ matches any URL starting with /images/.
• ~* \.jpg$ matches URLs ending with .jpg (case-insensitive regex).
• / is the default catch-all location.

Nginx will use its priority rules to decide which block handles a request.

Commands

Check the nginx configuration file for syntax errors before reloading.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the new configuration without stopping the server.

Terminal

nginx -s reload

Expected Output

No output (command runs silently)

Send a request to test the exact match location block.

Terminal

curl -i http://localhost/exact

Expected Output

HTTP/1.1 200 OK

Server: nginx

Content-Type: text/plain

Content-Length: 20



Exact match location

Send a request to test the prefix match location for images and regex match for jpg files.

Terminal

curl -i http://localhost/images/pic.jpg

Expected Output

HTTP/1.1 200 OK

Server: nginx

Content-Type: text/plain

Content-Length: 29



Prefix match location for images

Send a request to test the regex match location for jpg files.

Terminal

curl -i http://localhost/photo.jpg

Expected Output

HTTP/1.1 200 OK

Server: nginx

Content-Type: text/plain

Content-Length: 27



Regex match location for jpg files

Key Concept

If you remember nothing else from this pattern, remember: nginx chooses location blocks by exact match first, then longest prefix match, then regex matches, and finally the default catch-all.

Common Mistakes

Using regex locations without understanding they have lower priority than exact and prefix matches.

Nginx will not use the regex location if an exact or prefix match is found first, which can cause unexpected behavior.

Place exact and prefix locations carefully and test with curl to confirm which location handles the request.

Using multiple prefix locations that overlap without clear ordering.

Nginx picks the longest matching prefix, so shorter prefixes may never be used if a longer prefix matches first.

Design prefix locations so they do not unintentionally shadow each other.

Not testing configuration with 'nginx -t' before reload.

Syntax errors can cause nginx to fail to reload, leading to downtime.

Always run 'nginx -t' to verify configuration before reloading.

Summary

Use 'location =' for exact URL matches with highest priority.

Use 'location /prefix/' for longest prefix matches next.

Use 'location ~ regex' for regex matches after prefix matches.

Use 'location /' as a default catch-all location.

Test your configuration with 'nginx -t' and reload nginx to apply changes.

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