Redirects and Rewrite Rules
You can configure redirects and rewrite rules for your Netlify site by adding a
_redirects file to the root of your site folder (note, if you’re running a build command, the
_redirects file should end up in the folder you’re deploying. It’s not enough to have on in the root of your repository).
Setting up basic redirects is dead simple:
# Simple redirects from one path to another /home / /blog/my-post.php /blog/my-post /news /blog /google https://www.google.com
Just list the original path followed by the new path or URL.
Any # indicates a comment and everything following the pound sign will be ignored.
HTTP Status Codes
You can specify the HTTP status code for the rewrite. The default is 301 which will do a permanent redirect.
# Redirect with a 301 /home / 301 # Redirect with a 302 /my-redirect / 302 # Rewrite a path /pass-through /index.html 200 # Show a custom 404 for this path /ecommerce /store-closed 404
When the status code is 301, 302 or 303 Netlify will redirect to the target url. With any other status code Netlify will render the target url with the specified status code.
This means that you can define rewrite rules as well as redirects by specifying 200 as the status code.
You can easily setup a custom 404 page for all paths that doesn’t resolve to a static file. This doesn’t require any redirect rules. Just add a
404.html page to your site and it’ll be picked up automatically.
Our CDN edge nodes do URL normalization before the redirect rules kick in. This happens to make sure we can guarantee the highest possible cache hit rate and the absolute best performance for your site.
When “Pretty URLs” is enabled under processing settings for your site, Netlify will enforce consistent URL patterns.
A link to /about.html will be rewritten to /about in your HTML files and Netlify will enforce a redirect from /about/ to /about
A link to /about/index.html will be rewritten to /about/ and Netlify will redirect from /about to /about/
We don’t do automatic redirects from /about/index.html to /about/ since the former URL really does correspond to a file on our servers (and redirecting in this case would often cause trouble for single page apps loading partials over AJAX).
You can use placeholders in the origin and target paths:
This would redirect a URL like
An asterisk indicates a splat that will match anything that follows:
You can use the splat in your rewrites or redirects like this:
This would redirects paths like
You can also use query parameters in your URL matches. The following match will redirect a URL like:
/blog/my-blog-post with a
/story id=:id /blog/:id 301
Just add separate key/value pairs separated by space to match more than one query parameter.
History Pushstate and Single Page Apps
If you’re developing a single page app and want history pushstate to work so you get clean urls, you’ll want to enable the following rewrite rule:
/* /index.html 200
This will effectively serve the index.html instead of giving a 404 no matter what URL the browser requests.
Just like you can rewrite paths like
/api/* https://api.example.com/:splat 200
Now all requests to /api/… will be proxied through to https://api.example.com straight from our CDN servers. If the API supports standard HTTP caching mechanisms like Etags or Last-Modified headers, the responses will even get cached by CDN nodes.
Note on shadowing
By default, you can’t shadow a URL that actually exists within the site when using a splat or dynamic path segment. This means that even if you’ve setup the following rewrite rule:
/* /index.html 200
/partials/chat.html would still render the contents of that file, if that file actually exists. This tends to be the preferred behavior when setting up rewrite rules for single page apps, etc.
However, if you’re 100% sure that you’ll always want to redirect, even when the URL matches a static file, you can append an exclamation mark to the rule:
/app/* /app/index.html 200!
This will rewrite everything within /app/* to /app/index.html even if a file matches the URL.
GeoIP and Language-based redirects
Netlify supports GeoIP and language-based redirects directly from our CDN nodes.
This is ideal for large multi-regional sites where you want to send people to the right location based on their location or browser language.
GeoIP and language-based redirects are available on our enterprise plan. Please get in touch for more details.