Nginx Location Matching Rules and Proxy_pass Path Handling – Complete Guide

Location Matching Modifiers and Priority

Nginx supports five location modifiers. Their priority from highest to lowest is: = – exact match (highest priority) ^~ – longest prefix match, stops regex checks ~ – case‑sensitive regex, evaluated in configuration order ~* – case‑insensitive regex, evaluated in configuration order

no modifier – ordinary prefix match, longest match wins (lowest priority)

Matching Order

Exact match ( =) – applies only when the request URI exactly equals the string after location.

Regex match ( ~ / ~*) – processed sequentially according to their appearance in the config; the first matching regex is used.

Longest prefix match ( ^~) – selects the location block with the longest matching prefix.

Ordinary prefix match – chooses the longest matching prefix; if multiple blocks match, the one defined first wins.

Default match ( location /) – catches any request not matched by the above rules.

Matching Examples

location = /exact { ... }          # exact match
location ^~ /prefix { ... }        # longest prefix match
location ~ \.(png|jpg)$ { ... }   # case‑sensitive regex
location ~* \.(jpg|png)$ { ... }  # case‑insensitive regex
location /general { ... }          # ordinary prefix match
location / { ... }                # default match

Request /exact → matches location = /exact.

Request /prefix/long → matches location ^~ /prefix (the ^~ modifier outranks ordinary prefix).

Request /image.PNG → matches location ~* \.(jpg|png)$ (case‑insensitive regex).

Request /general/path → matches location /general.

proxy_pass Path Handling Rules

Path Concatenation

Trailing slash in proxy_pass location /api/ { proxy_pass http://backend/; } Request /api/user → forwarded URL http://backend/user.

No trailing slash in proxy_pass location /api { proxy_pass http://backend; } Request /api/user → forwarded URL http://backend/api/user.

Regex location

location ~ ^/app/(.*) { proxy_pass http://app/$1; }

Request /app/v1/data → forwarded URL http://app/v1/data.

Path Rewrite

Using rewrite can strip or modify the URI before proxying:

location ~* ^/api/v1/ {
    rewrite ^/api/v1/(.*) /$1 break;  # remove "/api/v1/"
    proxy_pass http://backend;
}

Request /api/v1/user/123 is forwarded to http://backend/user/123.

Special Scenarios

Unix socket forwarding:

location /unix/ {
    proxy_pass http://unix:/var/run/backend.sock:/;
}

Avoiding automatic 301 redirects when the location lacks a trailing slash:

# Without trailing slash – may cause Nginx to redirect to "/app/"
location /app { proxy_pass http://backend; }
# Use exact match to prevent the redirect
location = /app { proxy_pass http://backend; }

Configuration Optimization

Place exact‑match location = blocks at the top of the file to reduce regex overhead.

Order high‑frequency regex rules early to improve matching efficiency.

Keep the URL format (presence or absence of a trailing slash) consistent between location and proxy_pass to avoid path‑concatenation errors.

Enable error_log and access_log to monitor matching behavior and fine‑tune the configuration.

Complete Sample Configuration

server {
    listen 80;
    server_name example.com;

    # Exact match for static file
    location = /favicon.ico {
        log_not_found off;
        access_log off;
        root /var/www/icons;
    }

    # Longest‑prefix match for API requests
    location ^~ /api/ {
        proxy_pass http://api_server;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # Case‑insensitive regex for image assets
    location ~* \.(jpg|png|gif)$ {
        expires 30d;
        root /var/www/images;
    }

    # Default catch‑all
    location / {
        root /var/www/html;
        index index.html;
    }
}

Explanation:

Exact match for favicon.ico disables logging to improve performance. ^~ /api/ forwards any request beginning with /api/ to the backend API server.

Regex ~* caches image files for 30 days.

The default location / serves static HTML files for all other requests.