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 Upgrading from Drupal 8 (or later).

To understand how Composer manages Drupal dependencies, see Using Composer with Drupal, and make sure the project is ready for Composer.

Basic steps

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.

1. 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 steps below.
2. Check Status report under Reports in the Administrative GUI. Fix all errors and warnings before proceeding.
3. Before updating, make a back up with Backup and Migrate or Drush, so you can roll back if anything goes wrong.
4. If you use Drush, update to minimum Drush 12.4.3 to be Drupal 10.2 compatible:
   composer update drush/drush
5. Update Drupal core with this command:
   composer update "drupal/core-*" --with-all-dependencies
6. Use Drush to run required database updates and rebuild caches:
   drush updatedb
drush cache:rebuild
7. Check Status report under Reports. Fix all errors and warnings.

For more tips and details, see the following sections.

Tips and details

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

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.

1. You can run the composer require command above to specify a new, pinned version of core. 
2. 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 than composer 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 Basic steps above and assumes Drush is installed.

1. Always take a backup of your files and database before updating.
   • drush archive:dump will backup your code, files, and database into a single file.
   • drush sql:dump will export just the database.
2. Read the core release notes. Some contributed modules or themes may need updating to work with a new minor version of Drupal core. Patch releases shouldn't require this. To detect the needed module or theme updates, you need to read the project page or release notes.
3. Activate maintenance mode using drush state:set system.maintenance_mode 1 and then drush cache:rebuild. (Note: updatedb activates maintenance mode.)
4. If you determined that some modules or themes need updating, follow the module update instructions.
5. 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 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.
6. 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'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
7. Next, apply any required database updates using drush updatedb and clear the cache using drush cache:rebuild
8. 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.
9. 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.
10. Deactivate maintenance mode using drush state:set system.maintenance_mode 0 and then drush cache:rebuild.
11. After deactivating maintenance mode, test the site also as an anonymous user.
12. 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 than composer 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.

Some other pertinent issues and blog posts with further help:

1. 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.
2. Updating to Drupal 8.5 with composer - a blog post by Eirik Morland (eiriksm) covering some problems going from 8.4 to 8.5.
3. Composer fail to upgrade from 8.4.4 to 8.5.0-alpha1 - plenty of ideas on how to resolve a Composer update problem.
4. 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.