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.