You can configure redirects and rewrite rules for your Netlify site by adding a
_redirects file to the root of your site folder.
Note that if you’re running a build command or site generator, the
_redirects file should end up in the folder you’re deploying. Some generators, like Jekyll, may also require additional configuration to avoid exclusion of files that begin with
_. (For Jekyll, this requires adding an
include parameter to
Setting up basic redirects is straight forward:
# Redirects from what the browser requests to what we serve /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/
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
/store 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 without an additional connection from the browser. 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/index.html even if a file matches the URL.
Handling hostnames and protocols differently
All of the examples so far assume configuration “for all hostnames, using the specified paths”. If instead you need to do something special for a domain alias or specific protocol (HTTP vs HTTPS), you’ll want a pattern more like this one:
https://blog.yoursite.com/* https://www.yoursite.com/blog/:splat 301! # http and https need separate rules http://blog.yoursite.com/* https://www.yoursite.com/blog/:splat 301! # other hostnames might proxy or redirect offsite https://frontend.yoursite.com/login/* https://backend.yoursite.com/:splat 200
See the above note on shadowing for the reasoning behind the
! - it is presumably the case that you have a /blog/index.html that you’d rather serve than your site’s main index.html in this case!
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.
When you add these redirect rules, Netlify automatically creates alternate headers to enable the redirection in our CDN nodes. This removes the need for a roundtrip to our origin servers and ensures that normal pages, besides country or language based redirects, are cached on the CDN nodes.
The easiest way to understand these redirect capabilities is to look at some examples:
# Redirect users in China, Hongkong or Taiwan to /china / /china 302 Country=cn,hk,tw # Redirect users in israel to /israel / /israel 302 Country=il # Redirect users with chinese language preference from /china to /china/zn-ch /china/* /china/zn-ch/:splat 302 Language=zh
The system is smart enough to flatten chains of redirect. So in the above case, if a user from China with Chinese language preference visits /china, she’ll get redirected directly to /china/zn-ch in one step. Our cache server will cache this redirect for any other users that would match the same country and language rules.
You can find a list of country codes here: http://dev.maxmind.com/geoip/legacy/codes/iso3166/
And language codes here: http://www.metamodpro.com/browser-language-codes
For languages, note that en will match en-US and en-GB, zh will match zh-tw and zh-hk, etc.
Role based redirect rules
Role based redirects let you restrict access to certain paths of your application only to users with granted JWT tokens. This access control is implemented in our CDN, removing the need for a round trip to our origin servers. This feature is only available in Paid plans.
Before setting up these rules, make sure your JWT client secret is properly configured in our Visitor Access Control panel.
With this feature, you can set role conditions per redirect rule, like this one:
/admin/* 200! Role=admin
The rule avobe, tells Netlify’s CDN to grant access to the
/admin path and everything under it only to users which JWT tokens include the admin role in their
app_metadata. Any other user that tries to access those URLs will be presented with a 404 page.
If you don’t want present a 404 page, you can set a fallback rule to redirect users to a specific page, like a login page. The next example adds a new rule to accomplish that:
/admin/* 200! Role=admin /admin/* /login 401
The second rule in the example is what we call a fallback rule. It tell’s Netlify’s CDN that it must redirect every user that’s not in the admin role to a different page.
You can also grant several roles access to the same path by chaining them with commas:
/private/* 200! Role=editor,admin
You can use this feature with authentication providers like Auth0, Stormpath or any other that can generate JWT tokes with roles metadata. To learn more about JWT tokens and app metadata, you can read more about them JWT specification.
You can test if the rules in your
_redirects file are correct at Netlify’s Playground. Copy your rules there and click
Test rules. The playground will list all the invalid rules in your file if there is any.
Notice something is incorrect or outdated?
First off, great eye! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.