Netlify Redirects & Rewrites: How to Use the _redirects File Effectively

The Practical Answer

Netlify lets you control how every request is handled by defining rules in a plain‑text _redirects file. Each line in the file becomes an edge‑level rule that runs before your static assets are served, giving you full control over permanent redirects, rewrites, and fallback handling for single‑page applications.

How It Works

When you push a _redirects file to the root of your repository, Netlify parses it during the build step. The resulting set of rules is uploaded to the CDN edge network. On each request, Netlify evaluates the rules in the order they appear; the first match wins. A rule can be a redirect (HTTP status 301 or 302), a rewrite (status 200, returning the target content without changing the URL), or a fallback that serves a static file when no other rule applies.

# _redirects example
# 1. Permanent redirect from an old page
/old-page.html  /new-page.html  301

# 2. Rewrite blog URLs to a catch‑all file
/blog/*  /site/blog/:splat  200

# 3. Fallback for a single‑page app
/   /index.html  200

In the second rule, :splat captures the wildcard portion of the source URL and injects it into the destination. Without it, query‑string parameters would be dropped.

Limits & Constraints

• Maximum of 1,000 rules per site.
• Each line must contain no more than four fields: from, to, status, and optional conditions.
• Total file size capped at 64 KB.
• Rules are evaluated strictly in the order they appear; later rules cannot override earlier ones.
• Static asset requests that hit the CDN cache bypass the _redirects processing unless the asset is missing or a cache miss occurs.

Common Pitfalls

• Forgetting to redeploy after editing _redirects – changes only take effect on the next deploy.
• Using spaces instead of tabs can confuse the parser; keep the file plain‑text with no hidden characters.
• Choosing the wrong status code: 301 for permanent redirects, 302 for temporary, and 200 for rewrites.
• Assuming query parameters survive a rewrite unless :splat or :query placeholders are used.
• Placing a generic catch‑all rule before a specific one – the first match wins, so order matters.

Verifying Your Rules

After pushing your _redirects file, you can confirm Netlify has processed it in two ways:

1. Netlify UI – navigate to Deploy → Settings → Domain Management → Redirects. The table lists each rule, its status, and the order.
2. Command line – run netlify dev locally to see the rules applied, or use curl -I https://your-site.netlify.app/old-page.html to inspect the Location header and status code. Example:

   curl -I https://example.netlify.app/old-page.html
   HTTP/2 301
   location: https://example.netlify.app/new-page.html
   

To double‑check the rule count and order, you can use the Netlify CLI command netlify redirect:list (if available) or simply review the UI table. If a rule appears out of order, edit the file and redeploy.

Conclusion

By placing a well‑structured _redirects file in your repo, you gain edge‑level control over URL handling without extra server code. Remember the ordering rules, keep the file under 64 KB, and verify after each change to avoid subtle navigation bugs.