Update procedure in Drupal 8

Last updated on
8 June 2017

Firstly, make sure you understand the difference between an update and an upgrade - these instructions are for updating one 8.x.x version of Drupal to a later, backwards compatible, 8.x.x version, not for upgrading to a new major release, e.g. Drupal 7 to 8 or 8 to 9.

Before you begin

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

    If you're using 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.

    Alternatively, you can create a .tar.gz of files and the database with drush archive-dump (however this is a legacy command, slated for removal in Drush 9, which only covers files under /web).

  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 when updating production servers.

Automated Updates with Composer

If you've not used Composer before, please don't start from here, instead read the introduction.

If you already have a site that uses it, you can first identify what packages can be updated, without changing anything:

use either:  composer outdated

or: drush ups (aka drush pm-updatestatus)

Then do: composer update drupal/modulename --with-dependencies for each module you require.

Please Note: composer update --with-dependencies  updates core and all modules and is not recommended, as it could cause problems in some situations, and it's too difficult to see what's changed with everything being updated at once.

Next, apply any required database updates: drush updb

Clear the cache: drush cr

Check your site is OK:

  • check the status report page for errors
  • test the site - including as an anonymous user
  • turn maintenance mode off if you turned it on

On Production:

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.)

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.

Automated Updates with Drush

If you're using Drush, you can check for available updates: drush ups

Put the site into maintenance mode before updating using:

drush sset system.maintenance_mode 1
drush cr

Execute the updates:

Update Drupal core: drush up drupal
Update a single module: drush up module_name
Only apply security updates: drush up --security-only

This is a more selective/cautious approach to updating everything with drush up

Next, apply any required database and entity updates:
drush updb
drush entup

Also go through step 5. Re-apply any modifications and 6. If using Composer to manage PHP libraries below if you have made any modifications to files such as .htaccess, composer.json, or robots.txt, as Drush doesn't do this.

Now check your site is OK - look at the status report page, test the site, and finally turn maintenance mode off if applicable:

drush sset system.maintenance_mode 0
drush cr

Manual Updates (not recommended)

Log in as a user with the permission "Administer software updates".

  1. In the command line (shell), navigate into your drupal installation:

    cd /path/to/your/installation
  2. Put site into maintenance mode

    Via admin interface:

    Go to Administration > Configuration > Development > Maintenance mode.
    Check "Put site into maintenance mode" checkbox and click Save Configuration.

  3. Remove the 'core' and 'vendor' directories. Also remove all of the files in the top-level directory, except any that you added manually.

    rm -rf core vendor
    rm -f *.* .*

    If you made modifications to files like .htaccess, composer.json, or robots.txt, back them up now – you will need to re-apply them from your backup, after you've installed the new Drupal core.  For example, Acquia Dev Desktop places a .htaccess file in the top-level directory and without it, only the homepage on your site will work.

    Sometimes an update includes changes to default.settings.php (this will be noted in the release notes). If that's the case, follow these steps:

    • Locate your settings.php file in the /sites/* directory. (Typically sites/default.)
    • Make a backup copy of your settings.php file, with a different file name.
    • Make a copy of the new default.settings.php file, and name the copy settings.php (overwriting your previous settings.php file).
    • Copy the custom and site-specific entries from the backup you made into the new settings.php file. You will definitely need the lines giving the database information, and you will also want to copy in any other customizations you have added.

    You can find the release notes for your version at https://www.drupal.org/project/drupal. At bottom of the project page under "Downloads" use the link for your version of Drupal to view the release notes. If your version is not listed, use the 'View all releases' link. From this page you can scroll down or use the filter to find your version and its release notes.

  4. Download the latest Drupal 8.x.x release from https://www.drupal.org to a directory outside of your web root. Extract the archive and copy the files into your Drupal directory.

    On a typical Unix/Linux command line, use the following commands to download and extract:

    wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
    tar -zxvf drupal-x.y.z.tar.gz

    This creates a new directory drupal-x.y.z/ containing all Drupal files and directories. Copy the files into your Drupal installation directory :

    cp -Rf drupal-x.y.z/* /path/to/your/installation
    cp -f drupal-x.y.z/.* /path/to/your/installation

    If you do not have command line access to your server, download the archive from https://www.drupal.org using your web browser, extract it, and then use an FTP client to upload the files to your web root.

  5. Re-apply any modifications to files such as .htaccess, composer.json, or robots.txt.
  6. If using Composer to manage PHP libraries, update your /vendor directory with the following command:
    • composer update drupal/core --with-dependencies
  7. Run update.php by visiting http://www.example.com/update.php (replace www.example.com with your domain name). This will update the core database tables.

    If you are not logged in as a user with the "Administer Software Updates" permission, or the site maintenance account (as created during installation) you will be unable to access update.php – you can bypass this restriction as follows:

    • Open settings.php with a text editor.
    • Find the following line and change the value to TRUE:
      $settings['update_free_access'] = FALSE;
    • Visit the /update.php page again.
    • Once complete, you must change the setting back to FALSE for security reasons.
  8. Go to Administration > Reports > Status report. Verify that everything is working as expected.
  9. Go to Administration > Configuration > Development > Maintenance mode. Disable the "Put site into maintenance mode" checkbox and save the configuration.

  10. After updating, you can remove the Drupal release you downloaded and extracted earlier:

    rm drupal-x.y.z.tar.gz
    rm -rf drupal-x.y.z/