On this page
- Updating Drupal core with Composer
- List available Drupal updates
- Verify whether the project uses drupal/core-recommended or drupal/core
- Remove Drush before update?
- Update Drupal core code
- Update to the latest patch version of core
- Update to a specific version of core
- Unpinning from a specific version of core
- Run database updates
- Update the production environment (when applicable)
- Detailed update instructions
- Known issues and workarounds
- Problem: composer shows drupal/core updated but Status report does NOT show updated version
- Problem: drupal/core not updated with composer update
Updating Drupal core via Composer
This guide covers minor and patch version site updates, for example 10.0 to 10.1. For upgrading Drupal to a new major version, see How to upgrade from Drupal 9 to Drupal 10.
To understand how Composer manages Drupal dependencies, see Using Composer with Drupal, and make sure the project is ready for Composer.
- To update from a Drupal version earlier than 8.8.0, see Migrate composer project for Drupal earlier than 8.8.0.
- If you did not install Drupal via Composer, see Add Composer to existing sites.
Updating Drupal core with Composer
These are the basic steps, to do a minor update (for example 10.0 to 10.1) for a fully Composerized Drupal project, based upon the drupal/core-recommended
template.
- Check Status report under Reports in the Administrative GUI. Fix all errors and warnings before proceeding.
- Before updating, make a back up with Backup and Migrate or Drush, so you can roll back if anything goes wrong.
- If you use Drush, update to minimum Drush 12.4.3 to be Drupal 10.2 compatible:
composer update drush/drush
- Update Drupal core with this command:
composer update "drupal/core-*" --with-all-dependencies
- Use Drush to run required database updates and rebuild caches:
drush updatedb
drush cache:rebuild
- Check Status report under Reports. Fix all errors and warnings.
For more tips and details, see the following sections.
List available Drupal updates
composer outdated "drupal/*"
If there is no line starting with drupal/core
, Composer isn't aware of any update. If there is an update, continue with the commands below
Verify whether the project uses drupal/core-recommended
or drupal/core
Run:
composer show drupal/core-recommended
- If
drupal/core-recommended
is installed, this command returns information about the package. - If
drupal/core-recommended
is not installed, this command returns "Package drupal/core-recommended not found".
The difference between the two is that drupal/core-recommended restricts most dependencies to patch-level updates for maximum stability. drupal/core
is useful when you want to use the latest minor versions of dependencies and take care of testing that they work well. For more information see the README.
Remove Drush before update?
Some users prefer to remove Drush altogether before updating, and re-install after the update. This prevents issues with updating both Drupal core and Drush at the same time, which can happen.
Update Drupal core code
if you are using drupal/core-recommended
:
composer update "drupal/core-*" --with-all-dependencies
Note: some shells (eg. zsh, fish) handle asterisks package wildcards differently, so they need to be quoted.
If you are not using drupal/core-recommended
but instead only drupal/core
:
composer update drupal/core --with-dependencies
To simulate the update, and show you what would happen, without actually changing anything, add --dry-run
.
Update to the latest patch version of core
If you want to update your site to the latest patch version, but not the latest minor version, then add --with=
options for each drupal/core-*
dependency listed in composer.json
.
For example, if 9.4 is the current minor version and you want to update your site to the latest patch version of 9.3:
composer update "drupal/core-*" --with-all-dependencies --with=drupal/core-recommended:~9.3.0 --with=drupal/core-composer-scaffold:~9.3.0
This example assumes that drupal/core-recommended
and drupal/core-composer-scaffold
are the only Drupal core dependencies in composer.json
.
Update to a specific version of core
In general, we recommend that you do not specify a specific version of Drupal core when updating, unless you know that you want to pin to a specific version. If you do want to pin your site to a specific version, you can use the following example:
To pin your site to version 9.3.6 and update all dependencies accordingly:
composer require drupal/core-recommended:9.3.6 drupal/core-composer-scaffold:9.3.6 drupal/core-project-message:9.3.6 --update-with-all-dependencies
Warning: If you pin your site to a specific core version, that version will be added to the lock file, and future updates will not go past this version. Re-run the require command as specified below to return to an 'unpinned' version of core.
Unpinning from a specific version of core
If you are running a pinned version of Drupal core, and want to update your site to another version, you have two choices.
- You can run the composer require command above to specify a new, pinned version of core.
- You can unpin your core version, and update to the latest version of Drupal.
To unpin your version of Drupal, run this command:
composer require drupal/core-recommended drupal/core-composer-scaffold drupal/core-project-message --update-with-all-dependencies
Run database updates
For convenience we included the Drush commands necessary to complete an update, many people find Drush quicker and easier than the web-based admin area.
You can either use drush:
drush updatedb
drush cache:rebuild
Or you can visit [YOUR DOMAIN]/update.php
in a browser.
Update the production environment (when applicable)
If steps 1-2 were performed on a dev/staging environment:
- Push the changed composer.json and composer.lock files to production.
- run
composer install --no-dev
on production, rather thancomposer update.
- run drush updatedb or update.php
See Drupal updates and deployments for more details.
Detailed update instructions
This is a more detailed version of the Update Instructions directly above this section and assumes drush is installed.
- Always take a backup of your files and database before updating.
drush sql:dump
will dump the database.drush archive-dump
has unfortunately been removed from Drush 9, so you'll have to use a standard CLI tool to back up the needed directories - typically excluding the vendor directory.
- Read the core release notes. Some contributed modules or themes may need updating to work with a new minor version (e.g. 8.3 to 8.4) of Drupal core. Patch releases (e.g. 8.4.4 to 8.4.5) shouldn't require this. To detect the needed module or theme updates, you need to read the project page or release notes.
- Activate maintenance mode using
drush state:set system.maintenance_mode 1
and thendrush cache:rebuild
. - If you determined that some modules or themes need updating, follow the module update instructions.
- Determine if your Drupal install requires additional steps not included in this set of instructions:
- If you started your Drupal site using drupal-composer/drupal-project, please read the special considerations section for extra steps you may need to take the first time you update to version 8.8.0 or later
- If you did not install Drupal 8 via composer and it is not yet converted to a composer managed project, you'll need to do so by following the Add Composer to existing sites guide.
- Update Drupal core and all its dependencies:
- Run the following Composer command:
- If you are using
drupal/core-recommended
:
composer update "drupal/core-*" --with-all-dependencies
- Otherwise run:
composer update drupal/core --with-dependencies
- If you are using
- If you'd like to update to an unstable release, use one of these instead:
- For alphas, betas, RCs, etc.:
composer require 'drupal/core-recommended:^8.9' --update-with-all-dependencies
- For a development branch, e.g. 8.9.x:
composer require drupal/core-recommended:8.9.x-dev --update-with-all-dependencies
- For alphas, betas, RCs, etc.:
- Run the following Composer command:
- Next, apply any required database updates using
drush updatedb
and clear the cache usingdrush cache:rebuild
- If you are using config management to deploy your config, make sure to export the config with
drush config:export
after the database update because some core updates may change the structure of the config files or introduce new values to them. Add the option--diff
to view actual changes. - Check that your Drupal site is ok:
- Review the status report page for errors.
- If the Database Logging module is enabled, perform some basic operations and check the recent logs for errors, warnings, etc.
- Deactivate maintenance mode using
drush state:set system.maintenance_mode 0
and thendrush cache:rebuild
. - After deactivating maintenance mode, test the site also as an anonymous user.
- If you have separate dev/staging and production servers, ensure the updated composer.json and composer.lock files are on production and always run
composer install --no-dev
on production, rather thancomposer update
. The--no-dev
switch skips the installation of packages not intended for use on production sites.
Known issues and workarounds
Problem: composer shows drupal/core
updated but Status report does NOT show updated version
Summary: The composer update
command can silently fail causing a mismatch between what version of drupal/core
Composer shows versus what Drupal's Status report page shows. Removing the core directory and running composer install
should resolve the problem.
Detailed explanation: If you run the composer update
command above and composer outdated "drupal/*"
returns Everything up to date
, and the version returned with composer show drupal/core | grep versions
outputs the expected updated version, but visiting Reports > Status report shows the previous version (check core/lib/Drupal.php to see what the const VERSION
value is -- this is what will display on Status report), then composer update
has silently failed. To fix, remove the core directory and then run composer install
. For example:
rm -rf web/core/
composer install
This will re-download the updated version's core directory. Reload the Status report page to see the new version. (You may need to clear/rebuild caches (drush cache:rebuild
or Configuration > Development > Performance > Clear all caches) to see the change.)
Problem: drupal/core
not updated with composer update
If you run the composer update
command above but drupal/core
is not updated, there might be another dependency holding back the Drupal upgrade. You can check for blocking dependencies using the command composer prohibits
(synonym: composer why-not
). For example, if you are trying to upgrade from 8.4.5 to 8.5.0, you can run composer prohibits drupal/core 8.5.0
, and it should give a list of dependencies blocking the upgrade. Update those dependencies along with drupal/core
and it should work (e.g. composer update drupal/core "symfony/*" --with-dependencies
).
*If you have updated composer, and you find you have some dependencies that only work with older composer/installer versions, then include composer/* in the above command to fetch composer dependencies as well:
composer update drupal/core "drupal/core-*" "composer/*" --with-all-dependencies
Composer update problems are often related to abandoned composer templates or bad settings in composer.json. Make sure you are using a composer template like the one suggested in Chapter 3.5. of the Drupal User Guide "Using Composer to Download and Update Files". See Add Composer to existing sites for a step by step guide to manually adding composer to existing Drupal 8 sites that were previously installed without Composer.
As of January 2020 drupal-composer/drupal-project Composer template for Drupal projects is no longer the recommended template for Drupal 8.8 and above. Until Chapter 3.5 of the Drupal User Guide can be updated, please refer to The community guidelines for starting a site using composer project templates.
Some other pertinent issues and blog posts with further help:
- Update to Drupal core 8.4, a step by step guide - a blog post by PreviousNext covering the problematic 8.3 to 8.4 upgrade.
- Updating to Drupal 8.5 with composer - a blog post by Eirik Morland (eiriksm) covering some problems going from 8.4 to 8.5.
- Composer fail to upgrade from 8.4.4 to 8.5.0-alpha1 - plenty of ideas on how to resolve a Composer update problem.
- Having trouble updating your Drupal 8 Website? Then this Blog post is for you - Blog post for the new GoComposer plug-in that automates the update process & converts your site to the recommended template.
In case of errors and warnings occurring in the middle of the update process, it is recommended to read them carefully and search in the issue queues for possible solutions before going on. In case of fatal errors, it is always recommended to stop the updates and restart the whole process from scratch by using the backup recommended you made before.
Help improve this page
You can:
- Log in, click Edit, and edit this page
- Log in, click Discuss, update the Page status value, and suggest an improvement
- Log in and create a Documentation issue with your suggestion