Upgrading to Drupal 9 from Drupal 8

Upgrading to Drupal 9 from Drupal 8 kp37
Drupal Version

Notes, tips, and tricks for upgrading a Drupal 8 site to Drupal 9

Moving to Drupal 9 from Drupal 8 does not involve near as much planning and preparation work as previous major version upgrades thanks to changes the Drupal organization has made to the development process.  Instead of Drupal 9 introducing a new batch of features, new features have been added gradually over the major point releases of Drupal 8.  The key changes with the first release of Drupal 9 will be to remove deprecated (old and no longer used) code, and to upgrade the underlying Symfony framework.  On the surface, though, you should not see any notable differences between Drupal 8.9 and Drupal 9.0, assuming you have prepared your site properly.


Basic Requirements

  • Drupal 9 requires PHP 7.3 or higher (7.4 is preferred). If you are on OIT Web Hosting, you should be able to set your PHP version now via your site's Plesk Control Panel.

  • Drupal 9 requires a settings.php change:
    • The line beginning with "$config_directories['sync'] =" has to be changed to "$settings['config_sync_directory'] ="
    • Note: You can do this before upgrading, as Drupal 8.9 will work with either version of the setting.

  • To upgrade to Drupal 9, you must be on Drupal 8.9.0 or higher.
    • If you are already on 8.9, make sure you have the latest patch release to get the smoothest transition
    • If you are on anything earlier, upgrade to the latest patch release of 8.9 first, then upgrade to the latest 9.0 release.

  • Drupal 9 requires all active themes and modules to declare Drupal 9 compatibility:
    • Compatibility is indicated by a line in the theme or module's .info.yml file that starts with "core_version_requirement:"
    • Check and update all custom and contrib modules.
  • Drupal 9 (as did Drupal 8.9) uses CKEditor 4.14.0, but Drupal 9 seems to be stricter about CKEditor plugins. If you are using any add-on CKEditor plugins, check each one to see if there's a 4.14 specific version and upgrade as needed. Composer should maintain the compatible plugin version with a Drupal 9-compatible release.

    As an example, Balloon Panel, used by Accessibility Checker, was one that needs to be up-to-date to work in Drupal 9.

Checking Module / Theme Compatibility

There are several tools available that are supposed to check your site's modules and themes for Drupal 9 compatibility. The present options either require the ability to run PHP at the command line or require your site to be managed through Composer (such as Drupal Express websites).

Upgrade Status Module

The Upgrade Status module can perform a website audit to determine which modules, themes, and add-ons are Drupal 9 compatible.

Command Line

If you are comfortable with running simple commands at the Linux command line, you can get a quick overview of your modules declared compatibility by going to the main modules directory and running the following command:

  grep "core" */*info*

For any module where you do not see a line with "^9" near the end, you'll need to do some testing and research to see if the module will work with Drupal 9.  Check first for a new major version release, and if there is none, you could try the instructions given below for testing a previously Untested Release to see if it causes any problems.


Once you've completed all of the preparatory steps, upgrading is the same as if you were upgrading to another point release of Drupal 8. 

As with any major update, make a full backup (filesystem and database) before you begin, just to be safe.

Afterward, test major website capabilities thoroughly, since a lot of old code has been removed and the underlying Symfony engine has received a major upgrade.

Institute Communications update process

Refer to Institute Communications' gt_installer Drupal 8 to Drupal 9 update process to update GT Theme, GT Tools, and GT Profile to their latest versions.


Semantic Numbering - New Major Releases

As more time goes by, more module developers will move to the new semantic numbering system that is not tied to a Drupal version number (e.g. 7.x-1.0). Typically, if a module was at say version "8.x-3.5" then the next major release done under the new numbering system would be "4.0.0". You'll have to check carefully for this change, as Drupal alerts major version releases (8.x-3.5 to 4.0, for example) as "Other versions available".

However, in the case of modules like Webform, you may find you are expected to upgrade to the next major version when you upgrade your site to Drupal 9. Module version updates to the next major version can be done easily if you manage your site with Composer. Otherwise, you'll have to do this by hand at the filesystem level (Drupal won't upgrade to a new major version via the GUI).

As with most major version upgrades, manually run schema updates (go to update.php after updating).

Known Problem Modules

  • Devel has a new 4.0.0 release just for Drupal 9, but the popular Kint debugger sub-module is gone from 4.0.x. To get that functionality you have to use composer to install a Kint plugin for Devel 4.0.x or use the devel_kint_extras module. That's a big complication if your site is not set up to be managed by composer. As a workaround, you can download the PHAR version of Kint and manually include it in your site to get its functionality. Please note that the manual library process is not as streamlined an install as a prepackaged module.

  • Webform 8.x-5 is not compatible with Drupal 9 at all and will actually break the update.php process. If you use Webform, do not attempt to upgrade to Drupal 9 until you have upgraded Webform to its new 6.0 release.

Using composer to upgrade to Drupal 9

Using composer to upgrade to Drupal 9
Drupal Version

Drupal 8.9.x websites managed with Composer can be updated to Drupal 9.x by following the steps below. 

Before updating

Follow the directives on the Upgrading to Drupal 9 page:

  • Drupal 9 requires a settings.php change.

As with any major update, make a full backup (filesystem and database) before you begin.

Institute Communications update process

Institute Communications has provided an update script to assist with this upgrade. Refer to Institute Communications' gt_installer Drupal 8 to Drupal 9 update process to update GT Theme, GT Tools, and GT Profile to their latest versions. 

Upgrade Process

1. Install Upgrade Status and read the report

Install Upgrade Status like you would any other module:

composer require drupal/upgrade_status
drush en upgrade_status
drush cr

After enabling the module and clearing caches, navigate to Reports > Upgrade Status (admin/reports/upgrade-status). On the Upgrade Status page, make a note of the Remove and Update sections. 

Remove shows uninstalled modules and themes that are not compatible. You can remove each project using:

composer remove drupal/PROJECTNAME

Update shows each project which needs a Drupal 9-compatible release. For each project, go to the Issues (or the associated Drupal.org module page) and make a note of what version is required for Drupal 9 compatibility. 

2. Upgrade Drupal modules/themes to 9.x-compatible releases

Using the knowledge from Upgrade Status' Update list above, upgrade each module to its recommended Drupal 8 and Drupal 9 release:

composer require drupal/imageapi_optimize:^4.0

If you are unsure of how to write the composer require statement, each project release (e.g. drupal/imageapi_optimize:^4.0) has an Install with Composer text snippet to copy and paste.

Repeat this for each project that needs a new version for Drupal 9 support. Then, upgrade the database on your Drupal website by going to {website}/update.php.

Note for Drupal 9-only releases

Most modules, including all dependencies of the Drupal 8 Drupal Express install, have releases that are compatible with both Drupal 8 and Drupal 9:

  • Drupal.org module project download pages (e.g. faqfield:7.0) show compatibility with both versions with 
    Requires Drupal: ^8 || ^9

However, there are release that require just Drupal 9. For those modules (such as permissions_by_term:3.0), you will need to upgrade them while upgrading to Drupal 9.x.

3. Upgrade Drupal core to 9.x

From the drupal.org docs:

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

Please note the argument --no-update, which: 

We use --no-update to avoid a chicken-and-egg problem with mutual dependencies.

4. Commence upgrade!

Think you've updated all your modules and themes, and can begin the Drupal Core update to Drupal 9? Begin the update:

composer update

Make a note of any composer error message during this process. 

5. Update Drupal

Now, run the database updates.

If things broke

If composer goes haywire and you find yourself in purgatory, replace the composer.json with your pre-upgrade backup version, and delete the composer.lock file. Then, force composer to recheck and reinstall modules back to their old versions with:

composer install