Planning Your Drupal 9 Upgrade From Drupal 7

  • 11 minute read

This blog was originally published on in August 2020 and has been updated and republished here with permission. 

One of the real challenges in the Drupal community today is that roughly 60% of the reported installations are still on Drupal 7. This data (as of the time of this writing) shows that despite Drupal 8 being out for nearly five years, Drupal 7 still significantly dwarfs its predecessor in use.



With COVID-19 impacting many business plans this year, the Drupal community recently announced that it would extend the EOL for Drupal 7 into 2022. This means that Drupal 7 will actually outlive Drupal 8 due to the EOL of Symfony 3 (and the necessary EOL of D8 at the same time). At the same time, it continues to be a reminder that when you upgrade from Drupal 7 onto Drupal 8 or Drupal 9, it isn’t going to be easy. Acquia also announced that they would be extending commercial support of D7 until 2025 as a member of the Drupal 7 Vendor Extended Support program

The jump from D7 into these newer versions of the CMS is pretty significant, primarily because of the adoption of Symfony as the underlying framework of Drupal. With Symfony, comes a bunch of (much needed) upgrades to the “way Drupal does stuff".” This accounts for much of the complexity as we are introducing: Object Oriented PHP, Composer and Twig, simultaneously, as well as many improvements and new features.

The other significant challenge I want to call out here is that there is no direct upgrade path for those still on D7. You have options:

  • 1. Rebuild your site on D8/D9 and then migrate some/all of your content
  • 2. Use a product (such as Acquia’s Migrate Accelerator which is currently still in development) to “migrate.” This will still require some rebuilding. 

Discover Anew

The first thing I recommend doing is to step back, and pretend like your current website doesn’t exist. Many organizations I’ve worked for/with have lamented the “baggage” of their current CMS platform. Over the years of maintenance and content creation, many decisions are made. Some of them are good, but certainly not all of them.

Building an entirely new site on a new version of Drupal is a splendid opportunity to step back and start fresh. Review the requirements of your organization as it exists today (which may well be quite different than they were the last time you did a major refresh of your web presence.)

Treat this like any other requirements gathering exercise:

  • Engage stakeholders
  • Review requirements
  • Develop architecture
  • Build + Test the site

When Acquia does a Discovery, this is typically a 2-3 week process where we dive deep with stakeholders and technical experts to review the necessary functionality for a site/platform. We engage the design team. We work with the development team. We try to form as complete of a picture as possible for an organization’s requirements so that as we start planning the architectural approach to the site, we are doing so with an understanding of the complete landscape.

I frequently refer to Discoveries as a 10,000 foot flyover. At 10,000 you can see all of the features and shapes of the land below you, but you can’t see all of the details. A Discovery isn’t intended to be a deep dive into any one feature, but a broad review of all the features in enough detail to move the process forward.

Remember: this is an opportunity to refresh decisions! Don’t tie yourself to the existing platform just for the sake of doing so.

Reviewing the Old Site 

As your requirements gathering continues, use the old site/platform as a tool for exploring your requirements. Ideally, your Discovery will uncover which of the requirements from the old site that you still need. Then, you’ll do architecture planning to ensure that what you are doing on the old site still makes sense. I would argue that in many cases they won’t!

Remember, the architectural landscape of D7 is very different from D8/D9. There are many solutions you might have come to 5+ years ago that you wouldn’t today. This review is so important, because you shouldn’t just blindly re-architect those solutions in the same way! You may have significant redundancy (or worse, a lot of custom code) that isn’t necessary in today’s modern Drupal landscape.

As an example, I recently worked with a customer who had five different article types in their D7 site.

  • Article
  • News Article
  • Article + Map
  • Article + iFrame
  • Article + Table

The only real difference between any of these was how they were displayed. The underlying fields were the same. But the Map Article had a Map. And the News Article was routed to an alerting system and news view. With the improvements to the entity system in D8/D9 (particularly custom blocks and the inclusion of Layout Builder) I recommended to this customer that we change it up.

They should still have five content bundles, but instead of five content types, the new site should have:

  • 1 Content Type
    • Article
  • 3 Custom Block Types
    • Map
    • iFrame
    • Table
  • 1 Vocabulary
    • Article Type (e.g. News Article)

The end result is a much more reusable content architecture (the blocks can be used outside the scope of articles, if desired) and a less redundant configuration schema (as we won’t be maintaining five “virtually" identical content types).

I would also recommend as part of this process that you use the Drupal Spec Tool to document your content architecture (and many other common site building tasks) for your new D9 site.

Contrib Review

Next, as you continue your review of the old site, it’s time to dig into your contributed modules. You should know right up front that not all contrib from D7 is:

  • Ready for D9
    • e.g Libraries (not D9 compatible, yet)
  • Stable
    • e.g. Rules (Alpha release only)
  • Needed for D9
    • e.g. Views (in Core)
  • Still existent 
    • e.g. Admin Menu (replaced by Admin Toolbar)

Many of the modules you were using on your D7 platform may be stable for D9, but you need to go module by module to make sure that they truly are. I would also call out here that a lot of things you “used to need a module for” don’t necessarily need a module anymore. The plugin system in D9 makes writing custom code significantly easier (if, perhaps, a bit more technically complex given Object Oriented PHP) and the need for a bunch of contrib is less great today than it used to be. Drupal core can do more, meaning that contrib has to do less!

Take advantage of this situation to review your contrib modules and get rid of the cruft. I’ve seen more than one D7 platform with literally hundreds of contrib modules (many of which aren’t even actively used). Streamline down as much as you can!

Custom Review

Finally, take time to review the custom code that you have written. In my experience many custom modules on D7 sites are really Feature bundles. Remember that Features isn’t really a thing in D8/D9 and you’ll be using the configuration management system. Regardless, every line of custom code that you wrote in your themes / profiles / modules for D7 will have to be carefully reviewed. At minimum, you may have to tweak the code. At worst, you may have to totally rewrite it.

Keep in mind as you do this review that wherever / whenever possible prioritize:


This means that you should use custom code as rarely as possible. That’s not to say you shouldn’t write custom code! But wherever possible you should be using the tools maintained by the community. I’ve seen more than one organization heavily customize Drupal and then buckle under the stresses of trying to maintain a heavily customized codebase. Rely on the community. Rely on core. That’s what it’s for!

Getting Ready for the Update

Once you have your review and planning out of the way, you should be ready to start development. I do want to explicitly call back to some of the skills I mentioned early in this article, however.

Building in a D9 ecosystem should be done in a local virtual environment. It should utilize dependency management via Composer. You should be writing quality PHP code that follows Object Oriented principles. If your team isn’t ready to make this leap, you have time to start learning these skills and prepping for the update. Learning composer AND Object Oriented PHP while trying to work in a VM for the first time during your D9 upgrade is going to be a terrible experience. I speak from personal experience on the matter, I was trying to learn all these things (and more) when D8 was originally coming out. Break it down, take some time, and make sure your team is comfortable. Otherwise, the build is going to be off to a rocky start even before you truly begin.

In Conclusion 

The timer continues to count down on the EOL for Drupal 7. It’s time to make a plan to move to a more modern version of Drupal. Waiting until the last possible second will result in a rushed migration that may carry over technical debt and issues you don’t want in your new platform!

Take the time to carefully review the truly needed features and make as many improvements as possible. Drupal 9 is a wonderful CMS and I think you’ll be really pleased with all the enhancements. Drupal 7 is nine years old at this point! Think about all the incredible things that have happened in nearly a decade. The Drupal community has produced some pretty incredible things. I hope you take advantage of them.

Learn more about how to get your site ready for Drupal 9 in my recent webinar with Drupal4Gov: Future Proof Your Drupal Sites for D9.