How to Write Nginx Rewrite Rules

In this tutorial, you'll learn about How to Write Nginx Rewrite Rules. We cover key concepts, practical examples, and best practices.

The Problem

You need to redirect old URLs to new paths, restructure query parameters, or enforce trailing slashes. Without proper rewrite rules, users hit 404 errors on moved content.

Quick Fix

Step 1: Simple URL redirect

server {
    listen 80;
    server_name example.com;
    rewrite ^/old-page$ /new-page permanent;
}

This redirects /old-page to /new-page with a 301 (permanent) status. Use redirect instead of permanent for a 302 temporary redirect.

Step 2: Redirect an entire directory

server {
    listen 80;
    server_name example.com;
    rewrite ^/blog/(.*)$ /articles/$1 permanent;
}

The $1 captures everything after /blog/ and appends it to /articles/. A request to /blog/post-title goes to /articles/post-title.

Step 3: Redirect with query parameters preserved

server {
    listen 80;
    server_name example.com;
    location /search {
        rewrite ^ /new-search?q=$arg_q permanent;
    }
}

The $arg_q variable captures the ?q= query parameter from the original request and passes it to the new URL.

Step 4: Rewrite without redirecting (internal)

server {
    listen 80;
    server_name example.com;
    location / {
        rewrite ^/profile/(\d+)$ /user.php?id=$1 last;
    }
}

The last flag stops processing and serves the rewritten URI internally. The browser URL stays unchanged.

Step 5: Enforce trailing slash

server {
    listen 80;
    server_name example.com;
    rewrite ^([^.]*[^/])$ $1/ permanent;
}

This adds a trailing slash to any URL that does not already have one and does not contain a file extension.

Step 6: Force HTTPS with return (more efficient)

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

Using return is faster than rewrite for simple redirects. Prefer return over rewrite when no regex is needed.

Step 7: Test the configuration

sudo nginx -t
sudo systemctl reload nginx

Expected:

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

Alternative Solutions

Use try_files for fallback routing:

location / {
    try_files $uri $uri/ /index.php?$args;
}

This is common for single-page applications and frameworks like Laravel or WordPress.

Common Errors

Redirect loop: A rewrite rule that points to itself causes an infinite redirect. Use curl -I to check the Location header and ensure it differs from the original URL.

Rewrite not working: Verify that the rewrite module is compiled in: nginx -V 2>&1 | grep rewrite. If not present, rebuild Nginx with --with-http_rewrite_module.

last vs break confusion: Use last to stop rewriting and start a new location lookup. Use break to stop rewriting but continue processing within the current location.

Permanent redirect cached by browser: A 301 redirect is cached by browsers indefinitely. During development, use 302 (temporary) or append ? to bypass cache.

Prevention

• Test rewrite rules with curl -I before removing old URLs.
• Use return instead of rewrite for simple redirects — it is more efficient.
• Avoid complex regex chains that slow down request processing.
• Keep a changelog of URL changes to track redirect mappings.