Site Administration

Update Drupal's Minor Version for Drupal 8, 9, and 10

Now in Drupal, 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 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 the latest version of Drupal. For that, go to Migrate to Drupal 9 or 10.

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

Goal

Update Drupal core from one minor version to another either manually or via Composer.

Prerequisites

Note: This tutorial applies to Drupal 8.8.x and above, including the latest version of Drupal.

Quick reference

Updating Drupal's minor version requires the following steps:

  1. Make a backup of your existing database
  2. Update all Drupal core code to the latest version
  3. Perform any additional steps noted in the release notes
  4. Execute any require database updates via update.php

Depending on how you installed Drupal core the exact steps are different:

Evaluate an update release of Drupal

Drupal's version number is composed of three parts. As as an example suppose that version 8.2.4 is the current recommended release. The first digit, 8, indicates the major version of Drupal. The second digit, 2, is the minor version, and the third digit, 4, is 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 9, 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 Migrate to Drupal 9 or 10.

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.

Method #1: Manual update procedure

Use this method if you are not using Composer to manage your projects dependencies. This is likely the case if you started by downloading the .zip or .tar.gz file directly from Drupal.org when first installing Drupal core.

Note: If you started your Drupal project with 8.8.0 or greater (including Drupal 9) the downloaded files already contain the configuration necessary to use Composer and you can follow the process for using Composer outlined below to update if you would like.

Make a backup

Start by making a backup of your site's database. If you don't already know how learn more about creating a backup.

Put your site into maintenance mode

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

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.

After changing directories to the root of your Drupal site, remove 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.

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 update failed.

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 your site's update.php through a browser.

$settings['update_free_access'] = FALSE;

Take your site out of maintenance mode

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

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

Method #2: Update Drupal with Composer

If you're using Composer to manage your codebase follow these steps to update to the latest version of Drupal core.

This also assumes you're using Drush, but you could also perform the same tasks via the UX using the methods outlined above.

Make a backup

Start by making a backup of your site's database. If you don't already know how learn more about creating a backup.

Put your site into maintenance mode

Maintenance mode can be enabled using Drush, or via the UI following the steps outlined above.

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

Verify the required updates

Verify which dependencies will be updated with the following command:

composer outdated "drupal/*"

This wil result in output like the following indicating which version is currently installed, and which new version is recommended:

drupal/core                   8.8.0 8.8.1 Drupal is an open source content management platform powering millions of websites and applications.
...

Here 8.8.0 is the current version, and 8.8.1 is the version you'll have after updating.

Update Drupal core and dependencies

Note: The following steps will also work for minor and patch versions of Drupal 9 as well.

Are you depending on drupal/core package or drupal/core-recommended? You'll need to know this to proceed. Open the composer.json file in the root of your project and in the "require" section you should see one of either "drupal/core": "^8.8" or "drupal/core-recommended": "^8.8".

Use Composer to update whichever of the packages you have installed and any other dependencies that also need to be updated:

composer update drupal/core-recommended --with-dependencies

If this is successful you'll see a list of all the updates that happened:

Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 0 installs, 3 updates, 0 removals
  - Updating pear/archive_tar (1.4.8 => 1.4.9): Loading from cache
  - Updating drupal/core (8.8.0 => 8.8.1): Loading from cache
  - Updating drupal/core-recommended (8.8.0 => 8.8.1)

If you specified the wrong package, e.g.) drupal/core but your project uses drupal/core-recommended you'll see output like the following indicating there is nothing to update:

Loading composer repositories with package information
Updating dependencies (including require-dev)
Nothing to install or update

Run any required database updates

Run any outstanding database updates using Drush and then clear the cache:

drush updatedb
drush cache:rebuild

Take your site out of maintenance mode

Maintenance mode can be disabled using Drush, or via the UI following the steps outlined above.

drush state:set system.maintenance_mode 0
drush cr

Recap

In this tutorial we explained the difference between updates and upgrades, and minor versus major versions. Then we demonstrated two different approaches to updating Drupal core from one minor version to another. After completing one of these two processes you'll have updated your site from an older minor version of Drupal to the current release version.

Further your understanding

Additional resources