Update core via Composer (option 4)

Last updated on
7 February 2018

This documentation is incomplete. Add more information.

Before you begin 

If not already done, it is suggested to read this Introduction. Which summarized all your options to choose from when updating your Drupal 8.

Update Drupal 8 core 

Steps to update Drupal 8 core using Composer the dependency manager

  1. Always take a backup of your files and database before updating

    • Optionally, if you are using both composer and version control, also commit and push composer.json and composer.lock. Use mysqldump to backup your database. Modules such as Backup and Migrate are also available.

  2. Read the core release notes and, as a precaution, check the project page for each contributed module, theme or plugin: some may need updating to work with a new "minor" version (e.g. 8.3) of core.  Patch releases (e.g. 8.3.1) shouldn't require this, but it's advisable to test in a development environment first.

  3. Activate maintenance mode

  4. Choose one of the following two options:

    • Option 1: If you've not used Composer before, please don't start from here, instead read the introduction.
    • Option 2: If you already have a site that uses it, you can first identify what packages can be updated, without changing anything:
  5. Using the terminal/command line (shell), run the following command to shows a list of installed packages that have updates available, including their current and latest versions
    composer outdated
    • Note: This  command above check for available updates, then shows a list of installed packages that have updates available, including their current and latest versions. This is basically an alias for composer show -lo
  6. Using shell, run the following command for each module which needs updating
    composer update drupal/modulename --with-dependencies
    • Notes
      • The command above will work only if the module defines itself to Composer. In other words, the modules must come with a composer.json file. Without this file the command above would not work.
      • Another option is the composer update --with-dependencies command, which updates core and all modules. But this command is not recommended, as it is risky to cause problems in some situations, and it is too difficult to see what is changed with everything being updated at once.
  7. Next, using Drush apply any required database updates
    drush updb
    • Note: This command above is a short fordrush updatedb
  8. Still using Drush, clear the cache
    drush cr
    • Notes
      • "cr" is a short for "cache rebuild"
      • This command clears the cache_* bins in the Drupal database, and then rebuilds the site's containers
  9. Using Drupal, check your site is ok:
    1. Review the status report page for errors
    2. Test the site. Including as an anonymous user.
  10. Deactivate maintenance mode.
  11. On your Production environment:
    • You don't need to repeat the rest of the above process, as composer install will read the exact commit pointers for all packages from composer.lock, so you'll have identical versions of everything in both environments.
    • If you have separate dev/staging and production servers, ensure you copy/commit both your composer.json and composer.lock files to production and always run composer install --no-dev on production, rather than update.  (The --no-dev switch will stop any packages listed in 'require-dev' from being installed, typically modules for debugging and libraries for unit/behavioural testing.)

Known issues and work-arounds 

  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.