With the release of Drupal 8, core development has successfully transitioned to a regular release cycle. Drupal releases use the semantic versioning scheme to indicate whether a release is a major, minor or patch release. Since we're committed to making sure our tutorials are kept up-to-date with the latest and greatest version of Drupal we figured it would be a good idea if you knew how to keep your Drupal 8 site up-to-date with the latest point releases as well.

This tutorial will cover:

  • How to determine the type of update
  • The standard update procedure
  • Update Drupal using Drush
  • Update Drupal using Composer

This tutorial won't cover:

  • How to perform a major version Drupal upgrade, for example, from Drupal 6 or 7 to Drupal 8. For that, see our Drupal 8 Migration Guide.

But first, read on to learn about the different types of updates and releases that apply to Drupal 8.

Evaluate an update release of Drupal

Drupal's version number is composed of three parts. As of this writing, version 8.2.4 is the current recommended release. The first digit, 8, indicates the major version of Drupal. The second digit is the minor version, and the third digit the patch level. New patch-level releases are available monthly, while minor versions are currently released every six months. Since we keep our tutorials up-to-date with the most recent recommended version of Drupal, you can read more about the minor version releases on our blog for the 8.0.0, 8.1.0, and 8.2.0 releases.

First and foremost it's worth noting the differences between updating and upgrading. Typically, a transition between major versions, say between Drupal 6 or 7 and Drupal 8, requires an upgrade or a migration. Unlike an update, performing an upgrade is typically no small undertaking. On our blog we walked through a simple Drupal 7 to Drupal 8 migration which might give you a sense of what could be involved in the process. But since the Drupal upgrade process is typically quite complex, we have an entire series of tutorials devoted to the topic. So if your version of Drupal is a major version behind you can start learning about the upgrade/migration process with our Drupal 8 Migration Guide.

Drupal's release cycle now dictates that new minor versions are scheduled for release about every six months. This timeline helps organizations build their update plan into their development process. Minor releases may contain new experimental modules containing features that add additional functionality but aim to maintain backward compatibility within the major version. As a result, minor version updates are usually a relatively straightforward process. We'll cover three different ways to go about a minor version update below.

Patch releases may occur monthly, but only contain security and bug fixes. As such, the impact of a patch release is genuinely quite minimal, but may be important to address in a timely fashion, especially in the case of a security release. The process for upgrading Drupal is the same for both minor and patch releases.

Once you've determined whether your update is a minor or patch update, it's a good idea to read the release notes. These will provide a high-level overview of the changes that have gone into the new version. With this knowledge in hand you're ready to begin the actual mechanics of the update process. There are several different methods of updating your site outlined below. While I would recommend being familiar with all of the methods, they accomplish the same thing.

Regardless of which method you wind up using to update your Drupal site it is always a good idea to make sure you have a fresh backup available. Functional Drupal sites are composed of three components: code, files and a database. Hopefully the codebase for your site is already stored in some type of version control system. If it isn't, our Introduction to Git series would be a good place to start. There are several techniques you could use to backup the public (and private) files directories and your site's database. First, the Backup and Migrate module can be used to create and download backups right from within your web browser. Note, the Drupal 8 version of Backup and Migrate is still an alpha release so it will require additional testing before fully relying on it as your only option. Drush also has an option for generating a complete site backup with the archive-dump command. Running drush archive-dump from within your Drupal site will generate a SQL file with your database backup and a tarball containing your entire codebase along with the files directories.

Method #1: Standard update procedure

After creating a backup of your site, the standard update procedure involves putting your site into maintenance mode.

Put your site into maintenance mode

You can do this by visiting Administration > Configuration > Development or admin/config/development/maintenance from within your site.

Maintenance mode UI

Remove old code

With your site in maintenance mode you're now ready to update the codebase to the new release. The following steps should be run on a local development or staging site and then deployed to the live site using your regular deployment process. Start by removing the core and vendor directories, as well as any top level files you haven't added manually.

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

Apply new code and patches

Next move the Drupal files you've downloaded for the new release into place.

With the new Drupal code in place you can now reapply any modifications you have made to files like .htaccess, robots.txt, composer.json or any patches you've manually applied. Our projects typically include a text file that lists these modifications or patches for quick and easy reference during an update.

Update the database

By default, access to the update.php file in your codebase is blocked. In order to run that script from a browser to complete our site update we need to explicitly allow access. In your settings.php file locate the update_free_access setting, change it to TRUE and save the file. Now you can visit yoursite.com/update.php in a browser and run the database update script.

Pending update

Once the update script has finished you'll either see confirmation that it has been completed successfully, or a series of logged errors where the upate failed.

Successful update

With the update complete don't forget to flip the update_free_access setting back to FALSE to prevent others from being able to access it in settings.php.

$settings['update_free_access'] = FALSE;

Ta-da! You've just updated your Drupal site.

Method #2: Update Drupal with Drush

Now that we've walked through the standard update procedure, let's walk through the same process using Drush.

We've already mentioned how drush archive-dump can be used to create a backup of our codebase, files and database. We can use another Drush command to put our site into maintenance mode.

drush sset system.maintenance_mode 1 drush cr

With this in place we can then update the codebase by running two commands

composer update
drush pm-update drupal

We will still need to make sure any of our customizations to files like .htaccess and robots.txt are recreated. With these changes in place, database updates can be performed using:

drush updatedb

Assuming our updates complete successfully, the final step is to move the site out of maintenance mode and rebuild the registry and caches.

drush sset system.maintenance_mode 0
drush cache-rebuild

Method #3: Update Drupal with a Composer template

Another option for updating your Drupal code is to use this Drupal composer template to manage your codebase. The scaffolding provided by this project can be used to set up Composer templates for your Drupal projects. Once installed, this project allows you to manage, update and add dependencies (including contributed modules). Updating the Drupal codebase is accomplished by running

composer update drupal/core --with-dependencies

Since this project can help manage contributed modules as well as Drupal core, it's recommended that you avoid using it in combination with drush pm-update.

Following the best practices of the Composer project to manage your Drupal installation will also impact what third party code you store in your repository, and how. Since that's beyond the scope of this tutorial, I'd recommend becoming thoroughly familiar with the recommendations in the project's README before deciding on this approach.

Additional resources