The basics
Your site’s config usually lives in /etc/nginx/sites-available/ or /etc/nginx/conf.d/, inside a server { } block. Three rules of thumb:
- Prefer
returnoverrewrite.return 301 https://…;is simpler, faster and supports any status code.rewrite … permanentonly does 301 (andredirectonly 302). returndoesn’t add the query string for you. Use$request_uri(path + query) or append$is_args$args.- Always
nginx -tbefore reloading. A config error stops Nginx from reloading; a restart with a broken config takes the site down.
On managed hosts (Cloudways, Kinsta, Forge…) Nginx often sits in front of Apache or is configured for you. If you can’t edit Nginx directly, use your host’s redirect panel or the .htaccess recipes.
One page
location = is an exact match — the fastest kind, checked before anything else.
location = /old-page.html {
return 301 /new-page$is_args$args;
}
location = /about-us {
return 301 https://example.com/about;
}A whole domain
Give the old domain its own tiny server block. $request_uri carries the full path and query string across, so every page lands on its twin.
server {
listen 80;
listen [::]:80;
listen 443 ssl;
listen [::]:443 ssl;
server_name old-site.co.uk www.old-site.co.uk;
# Still needs a valid certificate, or HTTPS visitors see a warning first
ssl_certificate /etc/letsencrypt/live/old-site.co.uk/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/old-site.co.uk/privkey.pem;
return 301 https://new-site.com$request_uri;
}HTTPS + www in one hop
Two small catch-all blocks send everything to one canonical address in a single redirect. Your real site then only has to handle https://example.com.
# Any plain-HTTP request → https://example.com
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
return 301 https://example.com$request_uri;
}
# https://www → https://example.com
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name www.example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
return 301 https://example.com$request_uri;
}
# The real site
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name example.com;
# …
}Avoid the old if ($host = www.example.com) { … } pattern inside your main server block. Separate server blocks are clearer, faster and can’t accidentally catch other hostnames.
A folder
# /blog, /blog/ and /blog/anything → /news/…
location ~ ^/blog(?:/(.*))?$ {
return 301 /news/$1$is_args$args;
}Regex locations (~) are checked in the order they appear and win over plain prefix locations like location /, so put more specific ones first.
Hundreds of URLs: map
For a big redirect list — a site migration, say — don’t write hundreds of location blocks. A map is a hash table: it stays fast with tens of thousands of entries.
# In the http { } block, e.g. /etc/nginx/conf.d/redirects-map.conf
map $uri $redirect_to {
default "";
/about-us.html /about;
/services.php /what-we-do;
/blog/2019/hello /news/hello;
include /etc/nginx/redirects.list; # or keep the list in its own file
}# In your server { } block
if ($redirect_to) {
return 301 $redirect_to$is_args$args;
}if has a bad reputation in Nginx, but an if containing only a return is one of its safe uses. The bulk generator writes the map for you from a pasted spreadsheet.
Extensions & trailing slashes
Clean URLs (/about.html → /about), checking $request_uri — what the browser actually asked for — so Nginx’s internal lookups never loop:
if ($request_uri ~* ^/((?:[^?]*/)?)index\.html(?:\?|$)) {
return 301 /$1$is_args$args;
}
if ($request_uri ~* ^/([^?]+)\.html(?:\?|$)) {
return 301 /$1$is_args$args;
}
location / {
try_files $uri $uri.html $uri/ =404;
}Remove trailing slashes:
if ($uri ~ ^(.+)/$) {
return 301 $1$is_args$args;
}Gone pages
location = /discontinued-product { return 410; }
location ^~ /old-campaign/ { return 410; }Test & reload safely
sudo nginx -t && sudo systemctl reload nginx
curl -sI http://example.com/old-page | grep -iE "^(HTTP|location)"reload swaps configs without dropping connections. Then trace a few old URLs to check each lands in one hop.