Upgrading to Drupal 9

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.  If your site is on OIT Web Hosting, make sure you've requested a PHP upgrade before you try to upgrade to Drupal 9.

  • Drupal 9 requires a settings.php change:
    • The line beginning with "$config_directories['sync'] =" has to be changed to "$settings['config_sync_directory'] ="
    • Note: Not sure if you can do this before upgrading, but at a minimum you can duplicate the line and change the duplicate, then later delete the original after you've upgraded.

  • To upgrade to Drupal 9, you must be on Drupal 8.9 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 (and they, of course, need to actually be compatible, too.)
    • 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 modules in particular, but also check your contrib modules, too.
    • Note that at the moment, the Georgia Tech theme package and Mercury Reader package have not been certified Drupal 9 compatible, so you may want to wait for them to be certified before trying to upgrade.

  • Drupal 9 (as did Drupal 8.9) uses CKEditor 4.14.0, but Drupal 9 seems to be pickier 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.  (Balloon Panel, used by Accessibility Checker, is one that needs to be up-to-date to work in Drupal 9).

Checking Module / Theme Compatibility

For what it's worth, 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).

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.  More than ever, though, make a full backup (filesystem and database) before you begin, just to be safe. Afterward, test everything thoroughly since a lot of old code has been removed and the underlying Symfony engine has received a major upgrade.


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 (4.0.0 in this case) when you upgrade your site to Drupal 9. Module version updates to the next major version can be complete with Composer. Otherwise, it may be easiest to do this by hand at the filesystem level. As with most major version upgrades, you'll likely have to manually run schema updates (go to update.php after updating), as Drupal will only do a major version upgrade through the GUI if the previous major has been marked as unsupported.

Known Problem Modules

  • Devel has a new 4.0.0 release just for Drupal 9, which is fine and well, 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 it's functionality - it's not as streamlined an install as a prepackaged module, but if you need to use it, you should likely understand already how to manually set something like this up.

  • 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 (which is currently in alpha state, so your mileage with it may vary.).