Upgrade From Drupal 8 to Drupal 9: Complete Guide

  • Articles
  • August 9 2021
  • 11 min read
A metal ladder is seen going into clouds in the sky.

Gurpreet Kaur

Everything in our lives comes with an expiration date, even our lives itself, we aren’t going to be here forever, despite how much we may like it. We could still enjoy a good 90 years on earth, but the same cannot be said for technology.

Remember the phone, on which you just paid the last installment, it probably already has a new variant in the market, which would be more efficient than the device in your hand. The growth in technology and the passion we have for advancing forward are the reasons for our devices and software to lose its flair after sometime. And that makes us crave something newer and more powerful.

Every dimension of technology is going through the same and so is our domain of Drupal. When Drupal 8 was launched, I still remember being awed by its magnificence. Never did I think that I would want to be apart from it. And just then came Drupal 9, which was just about outdid the marvel of Drupal 8. And that meant that D8 now had an expiration date, which was sad. However, the benefits that came with the newer version had made digesting this fact a tad easier.

In this blog, we would be talking about the process involved along with the requirements of upgrading to Drupal 9. So, let’s find the answer to the very important question, ‘How to upgrade to Drupal 9?’

Easiest Upgrade of the Decade - Why Do You Need It?

Like I mentioned in the introduction, the launch of Drupal 9 meant that the earlier version would have their end-of-life looming over them. For both Drupal 8, that is going to be 28 November, 2021. 

What does that mean?

The one thing it doesn’t mean is that Drupal 8 would cease to exist. No, it would certainly be up and running, however, there won’t be any new releases for version 8 and it won’t be officially supported. 

Due to these facts, running your program on Drupal 8 can bring a host of problems for your web projects. There won’t be security updates, bug fixes and there certainly won't be any new modules for this version. As a result, you’d be prone to cyber attacks, you’d have higher chances of downtime, consequently your customers would really be happy with their experiences.

Here is a visual description of what I just discussed.

The timeline of Drupal support for its different versions can be seen.

So, you know what would be the consequences of staying put with Drupal 8, but shouldn’t be reason alone to make you want to take up Drupal 9. And it isn’t. D9 comes with a bucket load of benefits that would compel you to switch as soon as possible.

Ease of Upgrade 

The biggest benefit is the ease of upgrade that comes along with the latest version. After all, it has been called the easiest update of the decade. The reason for this is the fact that the D9 upgrade is not a complete overhaul of the previous versions, Drupal 9 is a whole new Drupal in one sense, but it is not a major version release. Unlike the preceding major updates, this one is more in tune with the prior version. 

Look at this diagram for better understanding. 

The differences between Drupal versions is shown.

Drupal 9.0.0 isn’t all that different from Drupal 8.9. The only prominent difference is that it is built through deprecating APIs and updated dependencies.

This also means that the acclimation period would be minimal. Developers, who have experience of Drupal 8 would not require much training. The working environment would be similar, just more modern.

Inventive and Progressive features 

Drupal 9 is going to be far more inventive and progressive than its predecessor. With consistent and cleaned up APIs, that’s probably a given. 

The new Olivero frontend theme and the Claro administration theme are perfect examples of Drupal 9’s innovative streak. While one is up and running, the other is still being stabilised.

A screenshot of the new Olivero theme in Drupal 9 is shown.
Olivera Frontend Theme|Source:

Perpetual bi-annual innovations

Upgrading to Drupal 9 would mean that you would be benefiting from its innovative cycle. In this version, you would not have to wait long for new feature additions, it would happen twice a year. Drupal 9.0.0 was released in June, 2020 and by December, 2020, version 9.1.0 had rolled out.

Learn more about Drupal 9 here:

The Upgrade Variation for Different Versions of Drupal 8

We’ve established that Drupal 9 and Drupal 8.9 are a lot similar to each other, however, the same cannot be said for versions 8.7 and earlier, which would lead us to believe that there is a difference between Drupal 8 and Drupal 9. This is why you would find that the upgrade process for specific versions of D8 to D9 is different.

Let’s understand how.

Version 8.7 and older 

Drupal 8.7 and older versions aren’t really compatible with Drupal 9. This means all the modules, themes along with the codebase would need to be updated to a version compatible with the update and that is Drupal 8.8 or 8.9. 

Without attaining the compatibility of each aspect of the preceding version to the succeeding, an update would not be likely. There are tools, like Upgrade Status (discussed in detail later), that help in ascertaining the compatibility, however, it would give an affirmative for 8.8 or later versions. 

Once you gain that , with your APIs, database, modules, and themes, and be certain there is no deprecated code even in version 8.8.x, only then would you be able to run update.php and finally upgrade to Drupal 9.

Version 8.8 and later 

Since it is advisable that you keep your projects updated to the latest version of Drupal, many of you might already still be on Drupal 8.8 or later.

If that is the case, your project would already be Drupal 9 compatible. All you would have to do then is check that compatibility and be certain it is there. You can do this by updating your contributed and custom modules and themes and using Upgrade Status check their concord and confirm the removal of deprecated code and move on to the update.

The upgrade process is somewhat similar to the previous one, it just has one less step.

The Tools that Aid the Upgrade 

Like any process and procedure, there are a specific set of tools that you would need to accomplish the Drupal 9 upgrade process; all in all there are five of them that you can choose from. The tools to upgrade Drupal 9 come in very handy in understanding and checking deprecations and consequently correcting them. Since eliminating deprecations and gain compatibility with Drupal 9 are the primary purposes of the upgrade, you can probably guess their importance.

The image displays a hexagon with all the tools needed for Drupal 9 upgrade mentioned in it.


Finding and removing deprecations in your code starts with the use of an IDE or a code editor that understands deprecations to the T. PHPStorm is one of them, it skips deprecated calls and alerts you of an alternative, which is crucial to making the deprecated code visible.

Drupal check 

Would it not be really convenient to simply run a standalone PHP executable from your command line and get a report of any and all deprecated code that was being used? I think it would be and Drupal-check does just that with a Drupal 9 compatibility check.

What is more convenient is that it can be integrated in the development processes and continuous integration systems. As a result, it becomes very easy to ensure that your custom code and contributed modules are deprecation free and Drupal 9 compatible.

Upgrade status 

Upgrade status is more or less similar to Drupal-check, but with a few additional features, making it the Drupal 9 upgrade module. Like Drupal-check, upgrade status too can perform a full site scan, including all the projects, and then evaluates the concord of the whole site to Drupal 9. It can also integrate with Drush. 

The upgrade status module scan includes; 

  • Checking the version of your Drupal site and suggesting updates; 
  • Checking whether your project meets the system requirements for Drupal 9; 
  • Informing you to update the contributed modules; 
  • And finally, checking to see whether there are any compatibility issues remaining.  

In terms of features, the upgrade status; 

  • Provides per project scans as well storage and exports of the results;
  • Provides problem categorisation in terms of deprecation versions; 
  • Provides detection deprecate Twig syntax; 
  • Provides exposure to deprecated library use; 
  • Provides notes on missing core_vision_requirement keys. testing system 

The testing system offers to detect the deprecated code in two ways.

  • The first is similar to upgrade status and Drupal-check, in the way that it runs deprecation testing through PHPStan.
  • And in the second, it configures your module’s test suite to fail upon reaching a deprecated code path. You would need the test to cover your code extensively for best results.


Rector performs automated deprecation fixes, but only for its common cases. It does have plans to build coverage for APIs that are the most deprecated. Drupal Rector is the implementation of the Rector concept on Drupal. Further, Upgrade Rector is Drupal’s integrated user interface for Rector. Its automated nature makes creating patches for both custom and contributed modules quite easy.

Because of its partial coverage, it's an incomplete solution. However, it can be integrated with Upgrade Status. 

The Environment Necessities for The Upgrade 

To prepare for Drupal 9, it is equally important to understand its environment requirements. This includes all the individual things and aspects you would need to be just right, affable and necessary for executing the upgrade of your Drupal 8 site.

The Drupal 9 environment requirements are mentioned categorised in three ways.

Modules and Theme Requirements  

A predominant part of this upgrade is upgrading the modules and theme for Drupal 9 from how they are in your version of Drupal. You may have guessed as much based on the previous sections, as they did lay some emphasis on making both the custom and contributed modules and themes Drupal 9 compatible. 

So, let’s find out how you can do that.

Updating custom modules 

Updating custom modules is highly dependent on Drupal-check. By now, you probably know why. When you run Drupal-check in your development environment and CI workflow, you’d not only know where the deprecated code is now, but also get to know as and new incompatibilities will arise.

Updating contributed modules 

For contributed modules, you would require to make a list and filter it out based on the amount of work needed. Then starting from the minimal work requirements, you should commence the compatibility process, hoping that the Drupal community would come to your aid and resolve the more difficult issues with the contributed modules. If not, then you can be the one to help your community, because someone had to.

Updating themes 

For themes, upgrade status comes quite handy, but first, you’d need to move from Twig 1 to Twig 2 and avoid any unsupported templates. Then upgrade status will alert you about any required changes. Try to treat the contrib base or sub-themes as modules, it’ll ease the update for you.

All of this becomes all the more easy when you filter out the required work based on the kind of work needed and start issuing tickets for the same in your sprints. And one by one, you’ll start coming closer to being completely compatible with Drupal 9.

System requirements 

There are specific system requirements that you need to be perfectly aligned with the upgrade. You could say that these are the minimum requirements for your system to work effectively.

  • Running Drupal 9 on Nginx would mean that you would have to update it to version 0.7.x; 
  • Running Drupal 9 on Apache would mean that version 2.4.7 is the one you have to be on;
  • Finally, in terms of PHP, you would need to be on version 7.3 to be able to work on Drupal 9. You should also know that 9.1.0 is supporting PHP 8.

Database and Hosting Requirements 

Hosting requirements act as a shield for your web project, so you have to be sure of them, especially after a major update. Here are the four major hosts for Drupal 9 and their requirements listed.

  • Using Drupal 9 with MySQL or Percona mandates an update to version 5.7.8+.
  • Using Drupal 9 with Maria DB mandates an update to version 10.3.7+.
  • Using Drupal 9 with SQLite mandates version 3.26+.
  • Using Drupal 9 with PostgreSQL mandate version 10 and the pg_trgm extension.

Strategic actions to implement for upgrading from Drupal 8 to 9

The Drupal 9 upgrade needs to be looked at with a sense of urgency, because time is of the essence. The end of life for Drupal 8 is November 2021, and after that, there won’t be any official support given to sites operating on it. The ones with a later version, being 8.8.x and 8.9.x, will continue to get support until November, 2022. So, missing the upgrade window is going to come at a loss of support, with security support being out of the equation for Drupal 8 since June 2020.

We’ve established that Drupal 9 isn’t all that different from Drupal 8, given the fact that it has no new features. The main difference is the removal of deprecated code. For that reason, upgrading to Drupal 9.0 cannot be regarded as a major upgrade, but a minor release; giving you all the more reason to upgrade.

And you need a strategy for that. 

I know what you are going to say, that I have already given you all the information you need for the upgrade, and that is true. However, what I’m going to say now is different as it pertains to the business side of things.

The development of your website 

More often than not, site upgrades are not isolated events, they come with a whole bunch of shenanigans that depend on it.  The overall development of your site, including its redesign and revamping of its information architecture encompass the upgrade strategy. 

With Drupal 9 being a minor upgrade without any migrations related to content, that means there won’t be any changes made to the information architecture. So, if you were planning to do that along with the upgrade, you’d need a new plan of action to follow it.

The upgrade would be colossally important for you, if you have major web developments in the works as they won’t be possible without it.

The stakeholders and fear of loss 

Many websites only contain features that were mandated by their stakeholders. These features often rely on contributed modules. How does this relate to the upgrade?

Because when you upgrade to Drupal 9, there are going to be a few contributed modules which would not be totally compatible with it. 

So, during the upgrade you have to be mindful of these modules. If you do end up losing some features and functionality, and they are crucial to satiate your stakeholders, you would need to find a way to ensure that you can deliver on them in Drupal 9.

The vendor partners and delays

 Finally, you might have a vendor, who is responsible for your developments and upgrades. If that is the case, you would need to get in touch with them soon because like you every other Drupal site and application is looking in the upgrade. And vendors would find it difficult to put you on their calendar in time. 

So, you need to book your slot as you would not want the added stress of finding and working with a new vendor for an upgrade that is deemed the easiest in a decade. 

To scan through all the FAQs on Drupal 9 upgrade, read this.


Upgrading to Drupal 9 has become a necessity, nobody can deny that. So, why not do it sooner rather than later and avail the benefits that it’ll bring along. And compared to the last major upgrade, updating to Drupal 9 is a breeze, even more so, if you have your Drupal site updated as it is advised. 

There is one more thing that I’d like to point out, when you're performing the upgrade, don’t focus on things like technical debt or half-baked features. Doing that would only delay the upgrade and not aid it. You can rectify them even after the update, raise a ticket to be on top of them. Remember the focus should be on making the site compatible for the upgrade, once that is done, then all you’ll need would be to run update.php, which would update Drupal and you’ll enter the D9 terrain.

Become our reader!

Get hand picked blogs directly in your inbox.
The subscriber's email address.