User Guide


rewrite performs internal URL rewriting. This allows the client to request one resource but actually be served another without an HTTP redirect. Rewrites are invisible to the client.

There are simple rewrites (fast) and complex rewrites (slower), but they're powerful enough to accommodate most dynamic back-end applications.


rewrite [not] from to...

Advanced users may open a block and make a complex rewrite rule:

rewrite [basepath] { regexp pattern ext extensions... if a cond b if_op [and|or] to destinations... }

"if" conditions

The if keyword is a powerful way to describe your rule. It takes the format a cond b, where the values a and b are separated by cond, a condition. The condition can be any of these:

Note: As a general rule, you can negate any condition cond by prefixing it with not_.


Rewrite everything to /index.php. (rewrite / /index.php will only match /)

rewrite .* /index.php

When requests come in for /mobile, actually serve /mobile/index.

rewrite /mobile /mobile/index

If the file is not favicon.ico and it is not a valid file or directory, serve the maintenance page if present, or finally, rewrite to index.php.

rewrite { if {file} not favicon.ico to {path} {path}/ /maintenance.html /index.php }

If user agent includes "mobile" and path is not a valid file/directory, rewrite to the mobile index page.

rewrite { if {>User-agent} has mobile to {path} {path}/ /mobile/index.php }

Rewrite /app to /index with a query string. {1} is the matched group (.*).

rewrite /app { r (.*) to /index?path={1} }

Rewrite requests for /app/example to /index.php?category=example.

rewrite /app { r ^/(\w+)/?$ to /index?category={1} }

Need help with this feature?

Join us in the Caddy forum, where the open source community gathers to share their knowledge.

Does your company use Caddy?

Purchase a commercial license to use Caddy with your business and for basic email support, along with other benefits!