Upgrade tool
The upgrade tool assists Strapi users in upgrading their Strapi application dependencies and code to a specific version.
Running the upgrade tool triggers the update of the application dependencies, their installation, and the execution of a series of codemods that automatically edit the application codebase according to the breaking changes introduced up until the targeted version.
The upgrade tool is a Strapi package and can be run from the CLI.
Scopeβ
While the upgrade tool helps upgrade applications and plugins, it doesn't cover every aspect of it.
β The upgrade tool supports:
- Updating the project's dependencies
- Applying automatic code transformation to existing files
- Installing or re-installing the correct dependencies for the project
β The upgrade tool doesn't support:
- Modifying the file tree by adding, removing or moving files and directories
- Migrating the application's data. This is handled by Strapi database migrations
After the upgrade tool completes its execution, it is strongly recommended to review the modifications made before re-running the app or plugin.
Version typesβ
Strapi version numbers respect the semantic versioning conventions:


- The first number is the major version number.
- The second number is the minor version number.
- The third number is the patch version number.
The upgrade tool allows upgrading to a major, minor, or patch version.
What the upgrade tool does depends on the latest existing version and the command you run.
For instance, if the latest Strapi v4 version is v4.25.9:
My Strapi application is currently on⦠| If I run⦠| My Strapi application will be upgraded to ⦠|
---|---|---|
v4.25.1 | npx @strapi/upgrade patch | v4.25.9 (because v4.25.9 is the latest patch version for the v4.25 minor version) |
v4.14.1 | npx @strapi/upgrade minor | v4.25.9 |
v4.14.1 | npx @strapi/upgrade major | Nothing. I first need to run npx @strapi/upgrade minor to upgrade to v4.25.9. |
v4.25.9 | npx @strapi/upgrade major | v5.0.0 |
v4.14.1 | npx @strapi/upgrade latest | v5.1.2 A confirmation prompt appears to make sure the major version bump is intended. |
Upgrade to a new versionβ
Before running the upgrade process, make sure you've created a backup of your codebase and database.