Netlify Docs
Ask Netlify

Contact

Configure & deploy site /Static routing /Redirects & rewrites /

Redirects and rewrites

You can configure redirect and rewrite rules for your Netlify site in two ways:

Framework considerations

If your site uses a specific framework, there may be additional redirect options or caveats for you to consider. Learn more in our framework docs.

Netlify processes and serializes your redirect rules across the _redirects and netlify.toml files. If the size of this output is too large, the deploy might fail.

If you need to set up 10,000 redirects or more, we recommend using wildcards or placeholders as much as possible. For a more complex redirect setup, Edge Functions can be a better option.

# Syntax for the _redirects file

In a _redirects file, each redirect rule must be listed on a separate line, with the original path followed by the new path or URL. Any line beginning with # will be ignored as a comment. Paths are case-sensitive and special characters in paths must be url-encoded.

Here is an example:

# Redirects from what the browser requests to what we serve
/home                /
/blog/my-post.php    /blog/my-post
/news                /blog
/cuties              https://www.petsofnetlify.com
/authors/c%C3%A9line /authors/about-c%C3%A9line

You can customize and alter the redirect behavior by adding options to the end of each line such as HTTP status code, country conditions, or language conditions. Visit the redirect options doc for more details on these and other configuration options including query parameters, forced redirects with !, domain-level redirects, and more. You can also use redirects for rewrites and proxies.

Make sure we can access the file

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 _config.yml.)

# Syntax for the Netlify configuration file

If you specify your redirect rules in your Netlify configuration file, you can use a more structured configuration format with additional capabilities such as signed proxy redirects. In a netlify.toml file, we use TOML’s array of tables to specify each individual redirect rule. The following keywords are available:

  • from: The case-sensitive path you want to redirect. Special characters must be url-encoded.
  • to: The URL or path you want to redirect to. Special characters must be url-encoded.
  • status: The HTTP status code you want to use in that redirect; 301 by default.
  • force: Whether to override any existing content in the path or not; false by default. Visit the shadowing instructions for more details.
  • query: Query string parameters REQUIRED to match the redirect. Visit the query parameters instructions for more details.
  • conditions: Conditions to match the redirect, including country, role, and cookie presence conditions.
  • headers: Additional request headers to send in proxy redirects.
  • signed: Name of an environment variable for signed proxy redirects.

You can specify any number of rules in your netlify.toml following that format:

[[redirects]]
  from = "/old-path"
  to = "/new-path"
  status = 301
  force = false
  query = {path = ":path"}
  conditions = {Language = ["en"], Country = ["US"], Role = ["admin"]}

## This rule redirects to an external API, signing requests with a secret
[[redirects]]
  from = "/search"
  to = "https://api.mysearch.com"
  status = 200
  force = true # COMMENT: ensure that we always redirect
  headers = {X-From = "Netlify"}
  signed = "API_SIGNATURE_TOKEN"

Visit the redirect options doc for more details on configuration options including placeholders, trailing slashes, and more. Check out the rewrites and proxies doc for details on rewrite-specific options.

# Rule processing order

The redirects engine will process the first matching rule it finds, reading from top to bottom. Rules in the _redirects file are always processed first, followed by rules in the Netlify configuration file.

The following example uses _redirects file syntax:

# This rule will trigger at /blog/my-old-title
/blog/my-old-title   /blog/my-new-title

# This rule will never trigger because the previous rule triggers first
/blog/my-old-title   /blog/an-even-better-title

Note that for each request, Netlify processes edge functions before redirects. For more information, visit our docs about the edge function declaration processing order.

← Redirect options →