Skip to main content

Documentation Index

Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt

Use this file to discover all available pages before exploring further.

In this tutorial, you’ll learn how to use Nginx’s rewrite directive to transparently redirect an old URL path to a new one. This approach preserves existing bookmarks and SEO value by issuing a permanent (301) redirect.

​
Scenario

Your site example.com originally served images from: 
https://example.com/images/pic01.jpg
After renaming the folder from /images to /pics, you want to redirect all traffic from /images/... to /pics/... without breaking links. A suitable rewrite rule is: 
rewrite ^/images/(.*)$ /pics/$1 permanent;
This captures anything after /images/ and issues a 301 redirect to /pics/....

​
Prerequisites

  • A running Nginx server (≥1.14)
  • SSH access to the server
  • Root or sudo privileges
  • A staging environment for testing
Always test changes in a staging environment before deploying to production to avoid downtime.

​
1. Prepare the Content Directory

On the Nginx server, duplicate the images/ folder under the document root (/var/www/html): 
cd /var/www/html
cp -R images/ pics/
Verify both directories exist: 
ls -l /var/www/html
Expected output: 
drwxr-xr-x 1 root root 4096 Feb 18 16:14 images/
drwxr-xr-x 1 root root 4096 Feb 18 16:29 pics/
Both directories should contain the same image files: 
ls -l images/

pic01.jpg  pic02.jpg  …  pic15.jpg

​
2. Test Before Rewriting

Ensure Nginx is running and serving files without any rewrite rules:
  1. Open your browser and visit:
    http://example.com/images/pic10.jpg
  2. You should see the image load directly from /images/pic10.jpg.

​
3. Review Initial Nginx Configuration

Open your server block configuration for example.com (commonly in /etc/nginx/sites-available/example): 
server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    index index.html index.htm index.nginx-debian.html;

    location / {
        try_files $uri $uri/ =404;
    }
}
Validate and reload Nginx: 
sudo nginx -t
sudo systemctl reload nginx

​
4. Add the Rewrite Directive

Edit the same server block and insert the rewrite rule before try_files: 
server {
    listen 80;
    server_name example.com;
    root /var/www/html;

    index index.html index.htm index.nginx-debian.html;

    location / {
        # Redirect all /images/... requests to /pics/...
        rewrite ^/images/(.*)$ /pics/$1 permanent;

        # Then attempt to serve the request
        try_files $uri $uri/ =404;
    }
}
Save the file, then test and reload: 
sudo nginx -t
sudo systemctl reload nginx
A typo in the regex or placement of rewrite can lead to redirect loops. Double-check the pattern and test thoroughly.

​
5. Verify the Rewrite

To avoid cached redirects, open an incognito/private browser window and navigate to: 
http://example.com/images/pic08.jpg
You should be permanently redirected (301) to: 
http://example.com/pics/pic08.jpg
and see the image served from the new location.

​
Quick Reference

StepActionCommand / Pattern
1Duplicate directorycp -R images/ pics/
2Verify directoriesls -l /var/www/html
3Review current Nginx server block/etc/nginx/sites-available/example
4Add rewrite rule before try_filesrewrite ^/images/(.*)$ /pics/$1 permanent;
5Test the redirect in private browserVisit /images/pic08.jpg

​
Conclusion

Using Nginx’s rewrite directive with regular expressions allows seamless URL remapping and preserves SEO by issuing 301 redirects. Always:
  • Validate your Nginx configuration (nginx -t)
  • Reload Nginx to apply changes
  • Test rewrites in a staging environment

Watch Video

Practice Lab