Skip to main content
Start of main content.

Preparing your site for Drupal 9

by kim.pepper /

Share this post on social media

Drupal 9 is just around the corner. Here's what you need to do to ensure a smooth upgrade.

Changes from Drupal 8 to Drupal 9

Unlike the Drupal 7 → 8 update, which required a rebuild and migrate, Drupal 9 is a simple incremental update from Drupal 8.

Third-party Dependencies

Drupal 8 is built upon 30+ third-party libraries. In order to keep Drupal stable, these have been kept at major version numbers throughout the Drupal 8 release cycle. Some of these will be end-of-life in coming years, so Drupal 9 is bumping these to newer versions in order to maintain long-term support coverage. The major dependency changes are:

  • Symfony 3.4.x  → 4.4.x
  • Twig 1.x → 2.x

In addition, Drupal 9 requires Drush 10.x or later.

Deprecated Code Removal

Drupal 8 introduced a backwards compatibility policy that required public APIs to remain stable while new features or improvements were added. The old APIs were marked as deprecated, but kept in place for backwards compatibility. This gives developers fair warning that code will be removed in future versions of Drupal giving them time to move to the new APIs.

Drupal 9 removes all deprecated code that has built up during the Drupal 8 release cycle.

Platform requirement changes

In addition, platform requirements have changed. Most importantly, this includes new minimum versions of:

  • PHP 7.3 or later
  • MySQL 5.7 or later

Getting Your Site Ready

Fortunately, there are only a few steps you need to follow in order to get your site ready for Drupal 9.

Update Contributed Modules to their Latest Version

Drupal 9 will work with modules that worked on Drupal 8, so there are no major rewrites required. This means the current module version naming scheme (e.g. 8.x-1.0) doesn't make much sense any more. It will gradually be replaced with a semantic versioning scheme (e.g. 2.1.0) as new module releases are published.

If you are a site builder, the easiest way to ensure your site is compatible with Drupal 9 is to keep your contributed modules up to date. You can check the status of your contributed modules using Acquia's Drupal 9 Deprecation Status page.

Replace Deprecated API Usage

Of course, many Drupal sites include custom modules. In order to get your own modules ready, you need to:

  • replace any usages of deprecated API usage
  • specify core version requirement to include Drupal 9

To automatically find usages of deprecated API usage, there is the excellent Drupal Check tool by Matt Glaman. Follow the installation instructions, then from the command line, run it against your custom module:

drupal-check web/modules/contrib/address

Almost all Drupal deprecations have handy instructions on the newer alternative API methods to use as well as a link to the change record that describes it in more details. For example:

drupal_set_message() is deprecated in Drupal 8.5.0 and will be removed before Drupal 9.0.0. Use \Drupal\Core\Messenger\MessengerInterface::addMessage() instead. See

Reading the change notice, we just need to change:

drupal_set_message("example message");


\Drupal::messenger()->addMessage("example message")

You can run drupal-check again and again until you have no more deprecation messages.

If you aren't comfortable with the command line, there is the excellent Upgrade Status module that you install to give you a user friendly report of what needs updating. There is also Drupal 8 Reactor which can automate some of this for you.

Specify Core Version Requirement

The last step is to specify your modules core compatibility. As per the change record there is a new key to add you your module info.yml file:

core_version_requirement: ^8 || ^9

This new key allows you to use composer-style version constraints and tells Drupal your module is compatible with Drupal 8 and 9.


That's it! There aren't many steps required to get your site ready for Drupal 9, and the best news is you can do it now and be ready the day Drupal 9 is released.



Drupal 9