Root vs Alias in Nginx: Key Differences and Usage

In Nginx, root sets the base directory for requests by appending the URI to it, while alias replaces the location part of the URI with the specified path. Use root when you want to serve files relative to a directory, and alias when you want to map a location to a different directory path directly.

Quick Comparison

This table summarizes the main differences between root and alias in Nginx.

Factor	root	alias
Purpose	Sets base directory for URI appending	Replaces location part with specified path
URI Handling	Appends full URI after location to root path	Replaces location prefix with alias path
Typical Use Case	Serving files from a directory matching location	Mapping a location to a different directory
Syntax Location	Used inside location block	Used inside location block
Trailing Slash Importance	Trailing slash optional but affects path	Trailing slash must match location for correct mapping
Common Mistake	Misunderstanding URI appending causes wrong paths	Incorrect trailing slash causes 404 errors

Key Differences

The root directive in Nginx sets a base directory path. When a request comes in, Nginx appends the full request URI after the location prefix to this root path. For example, if root /var/www/html; is set inside location /images/, a request to /images/pic.jpg will look for the file at /var/www/html/images/pic.jpg.

On the other hand, alias replaces the location prefix with the specified directory path. Using alias /var/www/images/; inside location /images/ means a request to /images/pic.jpg will serve the file from /var/www/images/pic.jpg directly, without appending the /images/ part again.

One critical difference is how trailing slashes affect behavior. With alias, the trailing slash in both the location and alias path must match exactly to avoid errors. Misconfiguration often leads to 404 errors. With root, the trailing slash is less strict but still affects the final path.

Code Comparison

Here is an example using root to serve files under /var/www/html for requests starting with /static/.

nginx

server {
    listen 80;
    server_name example.com;

    location /static/ {
        root /var/www/html;
    }
}

Output

A request to http://example.com/static/css/style.css serves the file from /var/www/html/static/css/style.css

Alias Equivalent

The equivalent configuration using alias to serve the same files would be:

nginx

server {
    listen 80;
    server_name example.com;

    location /static/ {
        alias /var/www/html/static/;
    }
}

Output

A request to http://example.com/static/css/style.css serves the file from /var/www/html/static/css/style.css

When to Use Which

Choose root when your directory structure matches the URI path, and you want Nginx to append the URI after the location prefix automatically. This is simpler for standard setups where the URL path mirrors the file system.

Choose alias when you want to map a location to a completely different directory that does not follow the URI structure. Use alias for more flexible mappings, but be careful with trailing slashes to avoid errors.

Key Takeaways

root appends the full URI after the location to the specified directory.

alias replaces the location prefix with the given directory path.

Trailing slashes must match carefully when using alias to avoid 404 errors.

Use root for simple directory mappings matching URI structure.

Use alias for flexible mappings to different directories.