Updating Drupal core via Composer

This documentation is incomplete. Add more information.

Having trouble updating to Drupal 8.8.0 or later?
Major changes were introduced in Drupal 8.8.0 as part of the Composer initiative, significantly improving long-term site management. However, there are important considerations for upgrading from earlier versions.

Getting Started

To understand how Composer manages Drupal dependencies, see Using Composer with Drupal. To decide whether Composer is right for you, compare available options.

This guide includes Drush commands to help complete the upgrade: many find Drush faster than the admin UI.

If your existing Drupal site has never used Composer, make sure it's ready for Composer before upgrading.

Upgrading Drupal 8 Core

First, check whether a core update is available:

composer update --dry-run "drupal/*"

This will list available minor or patch updates. Look for a line starting with drupal/core or drupal/core-recommended. If updates are shown, proceed.

One-Step Update

If you're experienced and aware of precautions, run:

composer update drupal/core --with-dependencies
drush updatedb
drush cache:rebuild

If using core-recommended, replace drupal/core accordingly.

Sites built using drupal-composer/drupal-project may require additional steps. See the special notes below.

Step-by-Step Update Instructions

1. Back up files and database:
   • drush sql:dump exports the DB.
   • Use CLI tools to back up directories (except vendor).
2. Review release notes.
3. Enable maintenance mode:

   drush state:set system.maintenance_mode 1 && drush cr

4. Update any modules/themes as needed: Update modules.
5. Update Drupal core and dependencies:

   composer update drupal/core --with-dependencies

   or use drupal/core-recommended if applicable.

6. Run:

   drush updatedb
   drush cache:rebuild
   

7. If using config management:

   drush config:export --diff

8. Check the status report page and logs for errors.
9. Disable maintenance mode:

   drush state:set system.maintenance_mode 0
   drush cache:rebuild
   

10. Test the site as an anonymous user.

In Production Environments

• Run composer install using composer.lock for consistent versions.
• Use composer install --no-dev to exclude dev dependencies in production.

Special Notes for Updating to Drupal 8.8.0+

See PreviousNext's blog post for a real-world update example.

Remove /vendor Directory

cd your_install_dir
rm -rf vendor

Migrate from webflo/drupal-core-strict

1. composer update
2. git add composer.lock; git commit
3. composer remove webflo/drupal-core-strict --no-update
4. composer remove drupal/core --no-update
5. composer require 'composer/installers:^1.7' --no-update
6. rm composer.lock && rm -rf vendor
7. composer require drupal/core-recommended:^8.8 --update-with-dependencies

Migrate from webflo/drupal-core-require-dev

composer remove --dev webflo/drupal-core-require-dev
composer require --dev drupal/core-dev

Updating Patches

If using composer-patches, you may need to reroll patches and update composer.json.

Resolving Soft Dependency Conflicts

composer require --update-with-dependencies \
drupal/core:^8.8.0 \
symfony/finder:^3.4 \
symfony/filesystem:^3.4
composer require --dev --update-with-dependencies \
drupal/core-dev:^8.8.0 \
symfony/debug:^3.4
composer remove -n \
symfony/finder \
symfony/filesystem
composer remove -n --dev symfony/debug

Update Configuration and Schema

drush updb
drush cr
drush config:export

Update settings.php

// Old
$config_directories['sync'] = 'foo/bar';
// New
$settings['config_sync_directory'] = 'foo/bar';

Known Issues and Workarounds

If composer update doesn’t update drupal/core, run:

composer prohibits drupal/core:8.5.0

This shows what’s blocking the update.

Use the recommended Composer template: Add Composer to existing sites.

As of Jan 2020, drupal-composer/drupal-project is no longer recommended for Drupal 8.8+. Refer to the community guide for using project templates.

Further Reading

• Upgrading to 8.4.0 and Drush 9
• Step-by-step upgrade to 8.4
• Updating to 8.5 with Composer
• Composer failed to upgrade from 8.4.4 to 8.5.0-alpha1
• Composer update guide from WebKings

Always read any error messages and search the issue queues. If fatal errors occur, roll back and restart the update using your backup.