Redirects and rewrites

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

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.

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

You can customize and alter the redirect behavior by adding options to the end of each line. Visit the redirect options and rewrites and proxies docs for more details.

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 path you want to redirect.
  • to: The URL or path you want to redirect to.
  • 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.
  • query: Query string parameters REQUIRED to match the redirect. Visit the query parameters instructions for more details.
  • conditions: Conditions to match the redirect, like country and role 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 file 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 and rewrites and proxies docs for more details on configuration 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

Redirects: HTTP Status Codes

Redirects: Custom 404

Redirects: Trailing Slash

Redirects: Placeholders

Redirects: Splats

Redirects: Query Params

Rewrites and Proxying

Rewrites & proxying: Limitations

Redirects: History Pushstate and Single Page Apps

Redirects: Proxying

Redirects: Note on shadowing

Redirects: Handling hostnames and protocols differently

GeoIP and Language-based redirects

Role-based redirect rules

Custom Headers in Proxy Redirects

Signed Proxy Redirects