Demo Configure URL Rewrite

This lesson shows how to use the Nginx rewrite directive to transparently map legacy URLs to new paths so existing bookmarks and external links keep working. The example scenario: a site previously served images from /images/ but has been reorganized to serve them from /pics/. We want requests for /images/... to continue working by rewriting them to /pics/... on the server. Example requests to preserve:

http://example.com/images/pic10.jpg
http://example.com/pics/pic10.jpg

How the rewrite works

Using rewrite ^/images/(.*)$ /pics/$1; tells Nginx to internally map any request starting with /images/ to the equivalent path under /pics/.
If you add the permanent flag (e.g. rewrite ^/images/(.*)$ /pics/$1 permanent;) Nginx will return an HTTP 301 redirect to the client. Without the flag the rewrite is internal: the browser URL remains /images/... but the server serves the file from /pics/....

Quick rule example:

rewrite ^/images/(.*)$ /pics/$1;

Using permanent (301) will update client caches and search engine indexes. Only use permanent when you are sure the change is permanent. For temporary behavior, omit the flag to keep rewrites internal.

Open the site on port 80 and verify an image URL works. For example:

http://80-port-wjfvg5fluvdar4xxv.kk-lab-dev.kodekloud.com/images/pic10.jpg

A screenshot of a minimalist webpage template titled "Phantom" with a large headline and a short paragraph of placeholder text. Below the header is a grid of colorful square feature cards labeled with words like "MAGNA", "LOREM", and "FEUGIAT".

Verify site content on disk

If the site root is /var/www/html, list the directory and confirm the images/ folder exists:

root@nginx:/var/www/html# ls -l
total 800
drwxr-xr-x 6 root root 4096 Feb 18 16:29 assets/
-rw-r--r-- 1 root root 19110 Feb 18 16:14 elements.html
-rw-r--r-- 1 root root 5464 Feb 18 16:14 generic.html
drwxr-xr-x 2 root root 4096 Feb 18 16:14 images/
-rw-r--r-- 1 root root 8710 Feb 18 16:14 index.html
-rw-r--r-- 1 root root 17128 Feb 18 16:14 LICENSE.txt
-rw-r--r-- 1 root root 966 Feb 18 16:14 README.txt

Preserve original content while moving

To keep the original images/ directory in place while making the content available under pics/, copy it:

root@nginx:/var/www/html# cp -R images/ pics
root@nginx:/var/www/html# ls -l
...
drwxr-xr-x 2 root root 4096 Feb 18 16:29 pics/

Confirm files inside images/:

root@nginx:/var/www/html# ls -l images/
total 136
-rw-r--r-- 1 root root 1259 Feb 18 16:14 logo.svg
-rw-r--r-- 1 root root 6311 Feb 18 16:14 pic01.jpg
-rw-r--r-- 1 root root 6084 Feb 18 16:14 pic02.jpg
-rw-r--r-- 1 root root 5788 Feb 18 16:14 pic03.jpg
-rw-r--r-- 1 root root 6499 Feb 18 16:14 pic04.jpg
-rw-r--r-- 1 root root 5232 Feb 18 16:14 pic05.jpg
-rw-r--r-- 1 root root 6704 Feb 18 16:14 pic06.jpg
-rw-r--r-- 1 root root 5606 Feb 18 16:14 pic07.jpg
-rw-r--r-- 1 root root 5889 Feb 18 16:14 pic08.jpg
-rw-r--r-- 1 root root 5808 Feb 18 16:14 pic09.jpg
-rw-r--r-- 1 root root 6489 Feb 18 16:14 pic10.jpg
-rw-r--r-- 1 root root 6338 Feb 18 16:14 pic11.jpg
-rw-r--r-- 1 root root 6261 Feb 18 16:14 pic12.jpg
-rw-r--r-- 1 root root 17129 Feb 18 16:14 pic13.jpg
-rw-r--r-- 1 root root 2580 Feb 18 16:14 pic14.jpg
-rw-r--r-- 1 root root 2560 Feb 18 16:14 pic15.jpg

Add the rewrite to your site configuration

Edit your site file (for example /etc/nginx/sites-available/example) and place the rewrite directive inside the location / block so requests for /images/... are mapped to /pics/.... A minimal example:

# /etc/nginx/sites-available/example
server {
    listen 80;

    server_name example.com;

    root /var/www/html;

    # Add index.php to the list if you are using PHP
    index index.html index.htm index.nginx-debian.html;

    location / {
        # Rewrite /images/<whatever> to /pics/<whatever> permanently
        rewrite ^/images/(.*)$ /pics/$1 permanent;
        # First attempt to serve request as file, then directory,
        # then return a 404 if not found.
        try_files $uri $uri/ =404;
    }
}

Test configuration and reload Nginx

root@nginx:/etc/nginx/sites-available# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

root@nginx:/etc/nginx/sites-available# nginx -s reload

Verify in the browser

Open the site in a fresh browser session or an incognito/private window and request an old /images/... URL. For example:

http://80-port-wjfvg5fluvdar4xxv.kk-lab-dev.kodekloud.com/images/pic08.jpg

With the permanent flag the browser will be redirected to http://.../pics/pic08.jpg (HTTP 301). Without the flag the server will serve content from /pics/pic08.jpg while the browser URL remains /images/pic08.jpg.

Helpful reference table

Directive / Flag	Behavior	Example
`rewrite ^/images/(.*)$ /pics/$1;`	Internal rewrite — server serves new path, client URL unchanged	`rewrite ^/images/(.*)$ /pics/$1;`
`rewrite ^/images/(.*)$ /pics/$1 permanent;`	301 Moved Permanently — client is redirected and may cache the result	`rewrite ^/images/(.*)$ /pics/$1 permanent;`

Resources and further reading

Always test rewrite rules in a staging environment before applying them to production. Regular expressions can be too broad or miss edge cases; validating behavior with multiple test URLs helps prevent unexpected redirects or broken resources.

Summary

Use rewrite to preserve legacy URLs when reorganizing site paths.
Choose between internal rewrites (transparent to the user) and redirects (inform client and search engines).
Test thoroughly and monitor caches when using permanent redirects.

Introduction

Install & Config

Intermediate Config

Security

Performance

Conclusion

Demo Configure URL Rewrite

Watch Video

Practice Lab