How to upgrade from Drupal 8 to Drupal 9

This page provides instructions on how to upgrade from Drupal 8 to Drupal 9. For upgrading from prior versions of Drupal (such as Drupal 6 and 7), see Upgrading from Drupal 6 or 7 to Drupal 8. 

There are separate instructions for minor and patch version site updates. (For example, updating from Drupal 9.3.6 to 9.3.8, or 9.2.14 to 9.3.8.)

1. Prepare to upgrade to Drupal 9

1. Ensure your hosting environment matches the platform requirements of Drupal 9.
2. Update to Drupal 8.8.x or 8.9.x (if not already on that version)
3. Update all contributed projects and ensure they are Drupal 9 compatible
4. Make custom code Drupal 9 compatible
5. Update core codebase to Drupal 9
6. Run update.php

If you're looking for step by step directions, you'll find more details in the upgrading section.

How do I upgrade to Drupal 9 from 8.7 or earlier versions of Drupal 8?

You should fully update your Drupal 8 site to the most recent version of both core and contributed modules and themes, prior to updating to Drupal 9. This means Drupal 8.8.x or Drupal 8.9.x and the most recent contributed modules versions that are compatible with those releases.

Drupal 8.8 is the first minor release of Drupal 8 that is fully API-compatible with Drupal 9.0.x, therefore contributed module releases prior to 8.8.0 are unlikely to be compatible with Drupal 9.0.0. We require updating to at least Drupal 8.8.0 prior to updating to Drupal 9 and the upgrade will not proceed until this is done. However more recent patch releases of 8.8.x and 8.9.x will have further bugfixes applied and are always preferred.

We have minimized the number and complexity of database updates required in order to update from Drupal 8.8 or 8.9.x to Drupal 9.0.x. By updating to the latest version of core first, this ensures your database is Drupal 9-ready, along with your contributed modules, so that only code changes and some smaller database updates need to happen all at once.

Make sure to update all contributed modules and themes and ensure they are all compatible with Drupal 9. They will also still be compatible with your Drupal 8.8+ site. Use Upgrade Status to check their compatibility. If your site has contributed modules which are not yet compatible with Drupal 9, you should cooperate with module maintainers and offer help where possible to make sure updates happen. Check the module's project pages for Drupal 9 plans as most key modules provided that. Read Help contributed modules prepare for Drupal 9 for more tips.

If you have custom code and/or themes, you should also confirm they are not using any code deprecated in 8.8.x or earlier for removal in 9.0.x, prior to attempting to update your site to Drupal 9.

Finally once every other component is Drupal 9 compatible, update the core codebase to Drupal 9 and run update.php.

Generally, it is recommended to keep up with minor updates of Drupal core as they are released. However if you are still on version 8.6.x or older, you may want to skip directly to 8.8.x in order to have upgrade path bug fixes applied. These are no longer backported to earlier versions.

If you are having trouble updating to 8.8.x, check the list of known issues and open a new issue if you can't find your problem there.

Note that Drupal 8.9 will have security support only until November 2021.

How do I upgrade to Drupal 9 from Drupal 8.8 or later?

Make sure to update all contributed modules and themes and ensure they are all compatible with Drupal 9. They will also still be compatible with your Drupal 8.8+ site. Use Upgrade Status to check their compatibility. If your site has contributed modules which are not yet compatible with Drupal 9, you should cooperate with module maintainers and offer help where possible to make sure updates happen. Check the module's project pages for Drupal 9 plans as most key modules provided that. Read Help contributed modules prepare for Drupal 9 for more tips.

If you have custom code and/or themes, you should also confirm they are not using any code deprecated in 8.8.x or earlier for removal in 9.0.x, prior to attempting to update your site to Drupal 9.

2. Upgrade to Drupal 9

Prerequisites

• Your site must be updated to the latest minor version. Upgrades are only supported from the final scheduled minor release and one previous (e.g. Drupal 8.8 and 8.9), not from earlier releases (e.g. Drupal 8.3). Follow the update instructions.
• You should upgrade any outdated modules on your site to their latest versions. Older module versions may not be compatible with Drupal 9.
• Check if you have deprecated code in your site that was removed in the next major version. Fix any deprecations, if required. The Upgrade Status module can help you with this. You might have to upgrade several modules.

The actual upgrade process will depend on whether your current site was built using Composer or tarballs (tar.gz files).

Perform the following steps from your Drupal 8 site's root (where composer.json lives).

1. Temporarily add write access to protected files and directories:
   

   chmod 777 web/sites/default
   chmod 666 web/sites/default/*settings.php
   chmod 666 web/sites/default/*services.yml

2. Next, you'll need to pull in both the Drupal 9 version of core-recommended and dev-dependencies packages as dependencies. We use --no-update to avoid a chicken-and-egg problem with mutual dependencies:
   

   composer require 'drupal/core-recommended:^9' 'drupal/core-composer-scaffold:^9' 'drupal/core-project-message:^9' --update-with-dependencies --no-update

   If you have drupal/core-dev installed:

   composer require 'drupal/core-dev:^9' --dev --update-with-dependencies --no-update

3. Now, actually perform the update to the code itself:
   

   composer update

   Note: If any of your packages doesn't have a release explicitly declared as D9-compatible, you will likely run into a dependency error when trying to update your codebase. There may already be a patch in the issue queue that you can use if you use to 'upgrade' the project to be drupal 9 compatible. Please refer to this documentation for more details on how to handle this situation: https://www.drupal.org/docs/develop/using-composer/using-drupals-lenient...

   Another, less recommended way to get around this, is you can add an alias to drupal/core, such as:

   composer require "drupal/core:9.0.0 as 8.9.0" --no-update && composer update

   (Make sure you replace 9.0.0 and 8.9.0 to whatever versions you are using in your installation.). This can lead to problems with modules that are *explicitly* d9 only, as they will not work in this scenario, but it might get you past where you need to be.

4. Run any pending database updates, required if you update module code and that module needs to update the database, either by visiting update.php in the browser, or with Drush:

   drush updatedb

5. When complete, restore read-only access to the sites/default directory:

   chmod 755 web/sites/default
   chmod 644 web/sites/default/*settings.php
   chmod 644 web/sites/default/*services.yml

   If you did run to include core 9.0 as 8.9 make sure to change the entry after a successful upgrade in your composer.json file. Otherwise you won't be able to install any Drupal updates.

   "drupal/core": "^9.0.0",

Things to check when update fails

Upgrading your site you may want to check composer.json for these lines:

"drupal/core":"^8.8.0", -> delete this line
"laminas/laminas-diactoros":"1.8" -> change to "^2"
"drupal/core-dev": "^8.8.0" -> change to "^9"

Upgrading a Tarball-based Drupal 8 site

Upgrading a tarball-based site from Drupal 8 to Drupal 9 with Drush requires an older version of Drush: Drush 8. See Update core via Drush for instructions on how to do this.

As of Drupal 9.4 sites built with tarball or zip file archives will no longer receive the same level of security support for core dependencies. Sites built with tarball or zip files should convert to using drupal/core-recommended to apply security updates more promptly than the above timeframe.