Nginx Redirect Generator

nginx redirects in depth: return vs rewrite, HTTPS canonicalization, and map-based bulk redirects

Redirects in nginx are typically faster and cleaner than in Apache because nginx is event-driven and most redirects can be expressed without invoking the regex engine. There are three techniques you should know — return, rewrite, and try_files — and picking the right one matters both for performance and for the response code the browser sees.

This generator emits one redirect line per pair you paste; the reference below explains every technique, the canonical HTTPS and www patterns, useful built-in variables, the map directive for hundreds of redirects, and how to validate the config before reloading.

return, rewrite, and try_files

• return — always preferred. return 301 https://example.com$request_uri;. No regex, no internal rewrite engine — nginx just sends the response.
• rewrite — supports regex and capture groups. rewrite ^/old/(.*)$ /new/$1 permanent; (permanent = 301, redirect = 302). Slower than return because the pattern must be compiled.
• try_files — not strictly a redirect, but indispensable for SPAs and PHP apps: try_files $uri $uri/ /index.php?$query_string; tries the file, then a directory, then falls back to the framework's front controller.

Dedicated server block for redirects

# HTTP to HTTPS, www and apex in the same hop
server {
  listen 80;
  listen [::]:80;
  server_name example.com www.example.com;
  return 301 https://example.com$request_uri;
}

# Drop the www on the TLS side
server {
  listen 443 ssl http2;
  server_name www.example.com;
  return 301 https://example.com$request_uri;
}

Keeping the redirect logic in its own server block (instead of branching with if) is the idiomatic nginx style and avoids the well-known "if is evil" gotchas inside location contexts.

Useful built-in variables

• $host — the hostname from the request line or Host header.
• $request_uri — original URI including query string (preserve the user's path on cross-domain redirects).
• $scheme — http or https based on the listener.
• $args / $arg_param — the entire query string or a specific parameter (e.g. $arg_id).
• $uri — normalized URI without the query string (use this when you do not want the query carried over).

Bulk redirects with map

map $request_uri $new_uri {
  default            "";
  /old-page          /new-page;
  /products/old      /products/new;
  /blog/2023/legacy  /blog/legacy;
}

server {
  listen 80;
  server_name example.com;
  if ($new_uri) { return 301 $new_uri; }
}

map scales gracefully to hundreds of entries because nginx builds a hash at startup. It is the right tool when you have a long mapping file exported from the old CMS — far cheaper than a wall of rewrite rules.

Validation and reload

sudo nginx -t              # syntax check, prints the file/line on errors
sudo nginx -s reload       # graceful reload (no dropped connections)
curl -I -L https://example.com/old-page  # confirm the 301 hop and the final URL

Compared with Apache, nginx is generally faster for static redirects because there is no .htaccess rescan on every request; Apache remains more flexible for per-directory rules controlled by the application owner.

FAQ

Is it OK to keep hundreds of redirects? Yes. nginx hashes map entries and resolves return in constant time, so even thousands of redirects barely affect latency. Avoid stacking many rewrite lines instead — those are evaluated sequentially with regex.

Does a 301 cache stick to clients forever? Practically yes — browsers cache 301 aggressively. If you ever need to walk a redirect back, override with add_header Cache-Control "no-store" before flipping it. Better practice: be sure of the destination before shipping a 301.

How do I move an entire subfolder to a new path? Use a location block: location /old/ { return 301 /new$request_uri; }. nginx will preserve everything after /old/, including the query string.

How do I redirect only when a query parameter is present? Use $arg_name inside if: if ($arg_legacy) { return 301 /new?id=$arg_legacy; }. Always validate with nginx -t after editing.