Nested location blocks in Nginx - Commands & Configuration

Introduction

Sometimes you want to handle different parts of a website differently. Nested location blocks in nginx let you match URLs inside other matched URLs to apply specific rules.

When you want to serve static files differently inside a specific folder of your website.

When you want to apply special headers or redirects only to a sub-path inside a main path.

When you want to proxy some requests to one backend and others inside that path to a different backend.

When you want to restrict access to a subdirectory but allow the main directory to be public.

Config File - nginx.conf

nginx.conf

server {
    listen 80;
    server_name example.com;

    location /images/ {
        root /var/www/static;

        location /images/thumbnails/ {
            root /var/www/thumbnails;
            add_header X-Thumbnail "true";
        }
    }

    location / {
        root /var/www/html;
        index index.html;
    }
}

This config defines a server listening on port 80 for example.com.

The location /images/ block serves files from /var/www/static.

Inside it, the nested location /images/thumbnails/ block serves files from /var/www/thumbnails and adds a custom header.

The location / block serves the main website files.

Commands

Check the nginx configuration file for syntax errors before applying changes.

Terminal

sudo 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

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

Send a HEAD request to check the headers for a file inside the nested location block.

Terminal

curl -I http://example.com/images/thumbnails/pic1.jpg

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:00 GMT

Content-Type: image/jpeg

Content-Length: 12345

Last-Modified: Tue, 31 Dec 2024 10:00:00 GMT

Connection: keep-alive

X-Thumbnail: true

Send a HEAD request to check the headers for a file inside the parent location block but outside the nested one.

Terminal

curl -I http://example.com/images/photo.jpg

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:00 GMT

Content-Type: image/jpeg

Content-Length: 54321

Last-Modified: Tue, 31 Dec 2024 09:00:00 GMT

Connection: keep-alive

Key Concept

If you remember nothing else from this pattern, remember: nested location blocks let you apply more specific rules inside broader URL matches.

Common Mistakes

Defining nested location blocks with paths that do not start with the parent location's prefix.

nginx matches nested locations only if their paths are sub-paths of the parent; otherwise, they are ignored or cause confusion.

Always start nested location paths with the parent location's path prefix exactly.

Using 'root' directive inconsistently inside nested locations causing wrong file paths.

Each 'root' resets the base directory, so nested roots must be carefully set to avoid serving wrong files.

Set 'root' carefully in nested blocks or use 'alias' if needed to avoid path conflicts.

Summary

Use nested location blocks to apply specific rules inside a broader URL path.

Test nginx config syntax with 'nginx -t' before reloading to avoid downtime.

Verify behavior by sending requests to URLs inside and outside nested locations.