How to Upgrade Webiny

Overview

Upgrading a Webiny project means bumping its dependencies to a newer release, running any associated migration scripts, and redeploying the updated project to your cloud infrastructure. Starting with v6, the upgrade process is streamlined — you can jump from any installed version to any higher version in a single step, without upgrading version by version.

All version-specific upgrade guides are located in the menu on the left, for example: 6.0.0 → 6.1.0.

🔥 Precaution Measures

Pre-Production Environments First

Whenever you are doing an upgrade, it is recommended that you first deploy your changes into one of your pre-production environments, like dev or staging. Once you have confirmed everything works as expected, you can start planning the move into production.

Production Data Backups

If you have any additional questions or concerns, feel free to send a message via the community Slack channel.

Upgrade Command

Starting with 6.1.0, there is a built-in command yarn webiny upgrade [version] that automatically upgrades your project to the specified version. For example, to upgrade to version 6.1.0:

You can also specify the version as latest, which upgrades your project to the latest available version. Omitting the version argument has the same effect as passing latest.

Once the upgrade completes, deploy your project using the yarn webiny deploy command.

Dependency Guard

The upgrade process includes a dependency guard that runs both before and after the upgrade, checking that your project’s dependencies match the versions expected by Webiny. If any mismatches are found, the guard will display warnings.

It is recommended to resolve these warnings, as out-of-sync dependencies can cause unexpected issues, especially on the Admin UI side.

Upgrade History

Each time a version upgrade is successfully applied, an entry is recorded in the webiny.history field of your project’s root package.json. Each entry contains the version and a timestamp:

This history serves two purposes:

• Skip already-applied upgrades — if you run the upgrade command again (e.g., after a failure partway through), versions that were already successfully applied are skipped automatically.
• Re-run with --force — if you need to re-apply an upgrade that was already recorded, use the --force flag to bypass the history check.

Available Flags

The upgrade command supports the following flags:

For example, to perform a dry run of the upgrade:

FAQ

While Upgrading, Can I Skip Versions, for Example From 6.0.0 to 6.10.0?

Yes. The upgrade command automatically upgrades your project to the specified version, regardless of how many versions are in between.

Once Upgraded, Do I Need to Re-Deploy the Project in Order to See the Changes?

Yes. After completing the upgrade steps, you need to re-deploy your project to see the new features and fixes online. The easiest approach is to deploy the entire project using the yarn webiny deploy command.

Before deploying to production, it is recommended to deploy into a test or preview environment first.

Is It Possible to Upgrade From V5 to V6?

The differences between these two versions are too vast for an automated upgrade. If you are interested in migrating an existing v5 project to v6, reach out via the community Slack channel to discuss the best approach.

How Can I Check the Current Webiny Version?

In your terminal, from the project root, run:

Where Can I Find Details on Beta Releases?

Details about beta versions are available on the create-webiny-project - npm page.

To set up a project with a beta release, run:

Additionally, set the WEBINY_VERSION environment variable to the desired beta version (e.g., WEBINY_VERSION=6.0.0).