How to set up redirects in Netlify

Introduction

Redirects are one of those things you don't think about until you really need them.

Maybe you changed a URL and don't want to break old links. Maybe you're migrating from another platform. Maybe you want a clean public URL that maps to something more complex behind the scenes. Whatever the reason, redirects are a core part of running a real website.

Netlify makes redirects surprisingly powerful and easy to manage. You can define simple URL redirects, advanced pattern matching, rewrites, proxy rules, and even conditional redirects based on things like country or language.

In this guide, you'll learn how Netlify redirects work, how to configure them correctly, and when to use redirects vs rewrites.

Redirects vs rewrites in Netlify

Before jumping into configuration, it's important to understand the difference between redirects and rewrites.

A redirect tells the browser to go somewhere else. The URL in the address bar changes, and the browser receives an HTTP status code like 301 or 302.

A rewrite serves different content without changing the URL in the browser. This is commonly used for single-page apps or clean URLs.

Netlify uses the same configuration syntax for both. The difference comes down to the status code you use.

Where Netlify redirects live

Netlify supports two ways to define redirects:

1. A _redirects file
2. The netlify.toml configuration file

Both options are valid. Which one you choose mostly depends on how your project is structured.

Option 1: Using a _redirects file

The _redirects file is a plain text file that lives in your published site folder.

For most static sites, this means placing it in:

• public/
• dist/
• build/

Depending on your framework, that's usually the folder Netlify deploys.

A simple example:

/old-page   /new-page   301

This redirects /old-page to /new-page using a permanent redirect.

Option 2: Using netlify.toml

If you prefer keeping configuration in one place, you can define redirects in netlify.toml.

This file lives at the root of your repository.

[[redirects]]
  from = "/old-page"
  to = "/new-page"
  status = 301

Functionally, this does the same thing as the _redirects file.

Basic redirect examples

Let's start with a few common cases you'll almost certainly need.

Redirect one page to another

/blog-old   /blog   301

Use this when you've renamed or moved a page and want search engines to update their index.

Redirect an entire directory

/docs/*   /documentation/:splat   301

The * matches everything after /docs/, and :splat passes it through to the destination.

So:

• /docs/getting-started → /documentation/getting-started
• /docs/api/auth → /documentation/api/auth

Redirect to an external site

/github   https://github.com/your-org/your-repo   302

This is useful for short, memorable URLs that point to external resources.

Choosing the right status code

Redirect status codes matter, especially for SEO.

The most common ones you'll use are:

• 301 – Permanent redirect. Use this when the old URL should never be used again.
• 302 – Temporary redirect. Use this when the redirect is temporary or conditional.

Netlify also supports 307 and 308, but unless you know you need them, 301 and 302 cover most cases.

Rewrites for single-page applications

If you're building a single-page app with client-side routing, you'll usually need a rewrite.

For example, React, Vue, or similar frameworks often rely on the browser handling routes like /dashboard or /settings.

To make this work on Netlify, add a rewrite like this:

/*   /index.html   200

This tells Netlify to serve index.html for all routes, while keeping the URL intact.

The 200 status code is what makes this a rewrite instead of a redirect.

Redirect priority and ordering

Redirects are processed from top to bottom.

This means more specific rules should come before more general ones.

For example:

/blog/rss   /feed.xml   301
/blog/*     /posts/:splat   301

If you reversed these, the /blog/rss rule would never run, because it would already match /blog/*.

When things don't work as expected, ordering is one of the first things to check.

Conditional redirects

Netlify supports conditional redirects based on things like country, language, or device type.

Here's a simple country-based example using netlify.toml:

[[redirects]]
  from = "/"
  to = "/fr"
  status = 302
  conditions = { Country = ["fr"] }

Visitors from France will be redirected to /fr, while everyone else stays on /.

These rules are evaluated at the edge, which makes them fast and reliable.

Testing redirects locally

If you're using the Netlify CLI, you can test redirects locally before deploying.

netlify dev

This runs your site locally with Netlify's routing logic, including redirects and rewrites.

It's the easiest way to catch mistakes without pushing a broken deploy.

Common mistakes and how to avoid them

A few issues come up again and again:

• Putting _redirects in the wrong folder – Make sure it ends up in the final published directory.
• Using 301 when you meant 200 – This breaks SPA routing. Rewrites must use 200.
• Overlapping wildcard rules – Always check rule order when using * and :splat.
• Forgetting trailing slashes – Netlify is forgiving, but consistency helps avoid surprises.

When to use redirects instead of links

Redirects are not a replacement for fixing internal links.

If you control the source code, update links directly whenever possible. Redirects are best used for:

• Backward compatibility
• External links you don't control
• Migrations and restructures
• Short or branded URLs

Used well, they make your site more resilient and easier to evolve over time.

Conclusion

Netlify's redirect system is one of its most underrated features. It starts simple, but scales all the way up to complex routing and edge-based logic.

Whether you're fixing broken links, migrating a site, or powering a single-page app, understanding redirects and rewrites will save you time and prevent subtle bugs.