> ## 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.

# Demo Configure URL Rewrite

> Demonstrates using Nginx rewrite rules to map legacy /images/ URLs to /pics/ paths, explaining internal rewrites versus permanent redirects, configuration, testing, and best practices

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:

```text theme={null}
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:

```nginx theme={null}
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:

```text theme={null}
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".](https://mintcdn.com/kodekloud-c4ac6d9a/ij3FNIPjp1w0Myd0/images/Nginx-for-Beginners/Intermediate-Config/Demo-Configure-URL-Rewrite/phantom-minimal-webpage-feature-cards.jpg?fit=max\&auto=format\&n=ij3FNIPjp1w0Myd0\&q=85\&s=4b90903e6534d7af2e8a5e84634d4331)

Verify site content on disk

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

```bash theme={null}
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:

```bash theme={null}
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/`:

```bash theme={null}
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:

```nginx theme={null}
# /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

```bash theme={null}
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:

```text theme={null}
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

* [Nginx rewrite module documentation](https://nginx.org/en/docs/http/ngx_http_rewrite_module.html)
* [HTTP status codes overview (MDN)](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)

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.

> **[Watch Video](https://learn.kodekloud.com/user/courses/nginx-for-beginners/module/c78ff9cb-c15d-4f85-92fc-abee5ed98b20/lesson/329f508c-8da5-4a0a-ad7a-f9504ab5e4f7)**

> **[Practice Lab](https://learn.kodekloud.com/user/courses/nginx-for-beginners/module/c78ff9cb-c15d-4f85-92fc-abee5ed98b20/lesson/7716ca0d-be85-45f9-a67a-11e298853b2b)**


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.