Strapi v5 is the latest major release, introducing performance improvements, flexible configuration, and new APIs. Upgrading requires updating dependencies, applying automated codemods, and making a few manual adjustments. Before starting, ensure backups are in place and all plugins are compatible with v5.

Prerequisites

  • Your Strapi v4 app must be running the latest v4 minor or patch version. If not, update it using: npx @strapi/upgrade minor
  • Node.js v18 or higher is required for Strapi v5.
  • Supported databases for Strapi v5 include PostgreSQL version 12 or higher, MySQL version 8 or higher, using the mysql2 driver, and SQLite version 3.24 or higher, using the better-sqlite3 package.
  • Ensure all plugins used in your project are compatible with Strapi v5 by checking their documentation or listings in the Strapi Marketplace.

Prepare for Upgrade

Start by backing up your database. In SQLite, the default file is data.db inside the .tmp/ folder. For PostgreSQL docs and MySQL docs, use the backup tools provided in their documentation. If your project is deployed on Strapi Cloud, create a manual backup before proceeding.

Next, back up your code. If you use Git, create a new branch for the migration. Otherwise, copy the project to a separate location. Finally, confirm which plugins in use support Strapi v5 by checking their documentation in the Strapi Marketplace.

Run Automated Migrations

Strapi provides an upgrade tool that installs v5 dependencies and applies codemods to address breaking changes. Run:

code
npx @strapi/upgrade major

This installs v5 dependencies and applies codemods to handle breaking changes.

Tip: If you develop Strapi plugins, other codemods handle some aspects of the helper-plugin deprecation. See the related breaking change for more information.

After the upgrade tool runs, search for __TODO__ in your code. These markers highlight areas needing manual migration especially when moving to the new Document Service API.

Document Service API: Additional information about the Document Service API can be found in the breaking change entry description, the specific migration guide, and the API reference.

Handle Manual Upgrades

These key changes may impact your Strapi app and need manual steps. For each one, read the linked breaking change and check if you still need to do anything after running the upgrade tool.

Data Migration:

If MySQL v5 is Not Supported, See Breaking Change

If Only Better-Sqlite3 is Supported, See Breaking Change

If Only mysql2 is Supported, See Breaking Change

If Lifecycle Hooks are Triggered Differently, See Breaking Change

Configuration:

Some Environment Variables are Handled by the Server Configuration, See Breaking Change

Custom Configuration Must Meet Specific Requirements, See Breaking Change

Admin Panel Customization:

The Helper-Plugin has been Removed, See Migration Reference

Migrate the API Consuming Side

Strapi v5 changes how REST and GraphQL APIs respond. Use compatibility flags to migrate gradually.

Migrate REST API Calls

Step 1: Enable v4 Compatibility: Add this header to your API request:

code
Strapi-Response-Format: v4

Step 2: Update Your Request: Adjust your REST queries based on the REST API Breaking Changes Guide.

Step 3: Test the API Migration: Make sure the client works as expected.

Step 4: Switch to Strapi v5 Format: Remove the Strapi-Response-Format header to use the new format.

Migrate GraphQL API Calls

Step 1: Enable v4 Compatibility: In /config/plugins.js (or .ts), set:

code
graphql: {
code
  config: {
code
    v4CompatibilityMode: true
code
  }
code
}

Step 2: Update Your Queries: Follow the GraphQL Breaking Changes Guide.

Step 3: Test Your Migrated GraphQL API Calls: Confirm your client still works.

Step 4: Switch to Strapi v5 Format: Set v4CompatibilityMode to false.