When should you use rewrite and when should you use return?

return is a terminal directive. It sends a status or redirect and stops processing the current request. rewrite changes the URI and may cause another location lookup, which makes it more powerful and easier to misuse.

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

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/nginx/tls/example.com.crt;
    ssl_certificate_key /etc/nginx/tls/example.com.key;

    location /legacy/ {
        rewrite ^/legacy/(.*)$ /v2/$1 permanent;
    }

    location /docs {
        rewrite ^/docs/(.*)$ /documentation/$1 last;
    }
}

Rewrite flags

• last stops the current rewrite set and searches for a new location
• break stops rewriting but keeps the current location
• redirect returns a 302; permanent returns a 301
• Without a flag, processing continues with the next rewrite directive
• A rewrite loop eventually fails with an internal redirection cycle

For a simple host or path migration, return is clearer and cheaper. Reach for rewrite when the new path depends on captured groups, and keep the regex anchored so it cannot match more than intended.