How do I upload a redirects.yaml file in Ghost?

Definition: A redirects.yaml file stores Ghost rules that forward requests from an old URL to a destination URL. As of 17 October 2026, Ghost documents a workflow of downloading the file from Ghost Admin, editing its rules in a code editor, and uploading it through Settings → Advanced → Labs.

Key facts

• Ghost's Redirects help page places the download and upload workflow in Labs, with the Open/Close toggle and Beta features tab.
• Ghost's Implementing redirects tutorial groups permanent redirects under 301 and temporary redirects under 302.
• Ghost's migration guide names the upload control Upload redirects, under Migration options in Labs.

Where does the download start?

The Redirects help page gives the path Settings → Advanced → Labs in Ghost Admin. The documented sequence opens Labs with its Open/Close toggle, selects Beta features, and downloads the existing redirects.yaml file. The downloaded file then opens in a code editor for changes to its redirect rules.

For a first configuration, Ghost's tutorial also describes creating a file named redirects.yaml directly in a code editor. A new Ghost publication has no redirects by default. The same tutorial recommends YAML for new redirects and says older JSON redirects continue to work.

How are redirect rules written?

YAML is the text format used for these rules. The help page requires spaces for indentation. Its example supplies this file structure:

301:
  /permanent-redirect-from: /permanent-redirect-to
  /permanent-redirect-from-2: /permanent-redirect-to-2

302:
  /temporary-redirect-from: /temporary-redirect-to

In this example, the paths on the left are the redirect sources, and those on the right are their destinations. Ghost's tutorial specifies a colon between the source and destination, with multiple entries on separate lines. It also allows external destination URLs. The 301 group represents permanent moves; the 302 group represents temporary moves.

How is the edited file uploaded and checked?

The migration guide identifies Upload redirects under Migration options at Settings → Advanced → Labs. That control selects redirects.yaml. The guide lists Upload routes YAML separately for routes.yaml, the routing configuration file.

After upload, Ghost's tutorial calls for testing by visiting a redirected URL in the browser. Its concrete example maps /editing-posts to /editing: opening the former checks whether the browser reaches the latter. This checks the source URL through the installed rule.

Related terms

• HTTP redirects
• HTTP status codes
• How do I change a Ghost post's URL?
• How do I write a regular expression redirect in Ghost?

FAQ

Can I upload a file created from scratch?

Yes. Ghost's tutorial says you can create redirects.yaml in a code editor for a first configuration and upload it from Ghost Admin.

How can I remove all custom redirects?

The same tutorial's removal instructions say to upload an empty configuration with 301: and 302: keys and no rules beneath them. This removes all existing redirects on the site.

Sources

1. Ghost, "Redirects", undated
2. Ghost, "Implementing redirects", undated
3. Ghost, "Migrating from Ghost To Ghost", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer