Upgrading to Strapi 5: Introduction and FAQ#

Strapi provides an upgrade tool to ease the process. The upgrade tool is a command line tool with some commands that handle the upgrade of the dependencies and the execution of codemods .

Follow the step-by-step guide to learn how to use this tool in the context of upgrading to Strapi 5.

Strapi 5 docs also provide a complete breaking changes database and dedicated resources to cover specific use cases.

Strapi 5 integrates a series of data migration scripts that are run once the application starts for the first time in Strapi 5.

However, please always backup your database (found at .tmp/data.db by default if using a SQL database) before performing any upgrade, as instructed in the step-by-step guide.

1. Create a backup and update your code locally, following the step-by-step guide.
2. Run the yarn deploy or npm run deploy commands from the Cloud CLI.
   

Strapi Cloud will deploy the updated code in Strapi 5 and will automatically run the data migration script.

• For REST clients, add the Strapi-Response-Format: v4 header while you refactor your code. The new response format breaking change shows where to add the header in curl, fetch, and Axios requests.
• For GraphQL clients, enable v4CompatibilityMode and follow the steps of the GraphQL API migration documentation to gradually remove attributes.
• REST responses continue to expose both id (legacy) and documentId when the header is enabled. GraphQL never exposes numeric id, so update your queries to use documentId even before you turn compatibility mode off.

Once every consumer reads the flattened format, remove the header so Strapi emits the Strapi 5 response shape by default.

Patch upgrades across Strapi v4 minors can fail the admin build with Cannot find module 'react' (or similar). Newer v4 lines expect react, react-dom, react-router-dom, and styled-components to be listed explicitly in your app package.json instead of relying only on transitive resolution.

Copy the versions from a fresh Strapi v4 project that matches your target release (for example run the official generator in a throwaway folder), then install and rebuild. A typical set looks like this:

"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-router-dom": "5.3.4",
"styled-components": "5.3.3"

Using a tilde or caret range on @strapi/strapi (for example ~4.25.22) is fine for patch updates; when you skip several minors, read the release notes and migration notes for each jump.

The archived v4 Developer Documentation still lives on .

Strapi does not ship an automated downgrade from Strapi 5 to Strapi 4.

Data migration scripts that run when Strapi 5 starts are not reversed by the product.

If you must return to Strapi 4, restore the database backup you created before the upgrade. Check out the Git branch or tag that still matches Strapi 4.

Reinstall dependencies so package.json and the lockfile match that snapshot.

Plan backups and staging environments using the step-by-step guide before you upgrade production.