Running Updates
Craft has a smart system based on Composer (opens new window) that helps you keep your site and plugins up-to-date. This page covers routine updates to dependencies, which we consider a distinct process from major-version upgrades.
# Using the Control Panel
When an update is available, users with the permission to update Craft will see a badge in the control panel next to
- Utilities
Click
- Utilities
- Updates
This section displays updates for Craft CMS and installed plugins, where each version has its own collapsible panel detailing relevant changes.
You can update one dependency at a time using its Update button, or update everything with the Update All at the top of the screen. If you don’t see these options, ensure the allowUpdates and allowAdminChanges settings are enabled in your current environment. We generally do not recommend applying updates in a non-development environment—see our workflow page for details.
Craft’s changelog (opens new window) will warn you of any critical changes at the top of the release notes. While there aren’t usually any warnings, it’s always a good idea to check the changelog and any upgrade guides before updating.
Urgent messages from changelogs (like security patches) are exposed as a banner in the control panel to all administrators.
After Craft successfully installs the updates, it will run any new migrations.
# Updating from the Terminal
# Craft CLI
The update console command can be used to update Craft and plugins.
To see available updates, navigate to a Craft project directory in your terminal and run this command:
You should see output like this:
Fetching available updates ... done
You’ve got two available updates:
- craft 5.4.8 => 5.4.9
- commerce 5.2.1 => 5.2.2
Run craft update all or craft update <handle> to perform an update.
To update everything all at once, run this command:
To apply a specific update, replace all with craft (to update Craft itself) or a plugin’s handle:
Fetching available updates ... done
Performing one update:
- commerce 5.2.1 => 5.2.2
Create database backup? (yes|no) [yes]:
Backing up the database ... done
Performing update with Composer ... done
Applying new migrations ... done
Update complete!
You can pass multiple handles in at once:
Craft will install the latest available version(s), unless you append :<version> to the handle:
After an update is performed from the CLI, Craft will apply any relevant migrations.
# Composer
craft update is mostly a wrapper around Composer—but you can use Composer directly for more control over the update process.
The main behavioral difference is that craft update will always set specific Craft and plugin versions (like 5.4.1 or 1.2.3), whereas Composer allows you to use version constraints (opens new window) (like ^5.3.0 or ^1.0.0) to define dependencies.
When using version constraints, composer.lock will still make sure you get a stable set of packages from composer install. To update all your packages to the most recent versions allowed by their constraints, run composer update. Update a single package by specifying it in the command: composer update craftcms/cms.
If you have used the Craft CLI in the past, composer update may do nothing!
Open composer.json, and look at the packages under the require key—if you see exact version numbers, Composer will never update those packages.
Keep in mind that manually altering constraints can lead to an irreconcilable set of packages—Composer will let you know about this before updating the lockfile. Generally speaking, the “major-version” constraints set automatically when using composer require should continue to work, while protecting your project from breaking changes in dependencies.
# Workflow
Every time you deploy your project, you should run composer install and craft up to bring that environment’s dependencies and database into agreement with your packages and their expected schema version.
The same applies when working with teammates! Any time you pull new code into a project, running composer install will guarantee you are working with the same set of packages as your collaborators. If you’re one for automation, you can even have Craft apply migrations and project config at the same time by adding a special hook to the scripts key in composer.json:
{
"require": {
"craftcms/cms": "^5.0.0",
"vlucas/phpdotenv": "^5.4.0"
// ...
},
// ...
"scripts": {
"post-install-cmd": "@php craft install/check && php craft up --interactive=0 || exit 0"
}
}
This tells Composer that after it has successfully installed packages from a lockfile (typically the result of running composer install), it should check if Craft is installed (@php craft install/check) and if so, run craft up non-interactively to apply migrations and project config. || exit 0 ensures that the command exits nominally, so as not to disrupt other processes that expect composer install to succeed.
# Licensing
When you buy a Craft Pro or plugin license, you are entitled to use that version in perpetuity—or any version that you update to, during the year of included updates. To get the most out of your Craft licenses, run updates frequently!
# Upgrade Guides
Each version of the Craft documentation contains an equivalent of the Upgrading from Craft 4 page, which covers the process of upgrading from one major version to the next.
Sometimes, there are significant changes to be aware of—even in minor or “point” releases. The most common changes that fit this criteria are deprecations. Deprecation notices will be accompanied by instructions for updating your code to work with the new APIs. Any features that are subsequently removed in a major release will also be noted in the new version’s upgrade guide.
Deprecation warnings will affect plugin developers more frequently than regular users—but it’s still a good idea to keep your eye on the Deprecation Warnings utility.
# Major Versions
For the smoothest upgrade experience, projects must be updated to the latest available minor version preceding a major version upgrade. We do not support “skipping” versions, so if your site is running Craft 3, you must first update to the latest 3.x version, then perform the 3.x → 4.x upgrade, then perform the 4.x → 5.x upgrade.
You should always upgrade to the latest release in a given major Craft version—for example, you can upgrade directly from 4.12.8 (or whatever the latest 4.x release is) to 5.4.9 (or whatever the latest 5.x release is).