Skip to main content
Header Image
March, 2020

Lessons Learned Upgrading Drupal 7 to Drupal 9

Chris Steins
Chris Steins
Founder & Senior Advisor

I surveyed several of my Urban Insight colleagues who have been through multiple upgrades to Drupal 9 for the lessons they've learned and challenges to expect as you take on your Drupal 7 to Drupal 9 (or Drupal 10) upgrade.  

Here’s a summary of their hard-won observations.

What is most important to keep in mind when planning for a Drupal 7 to Drupal 9 upgrade?


Rebuild vs. Upgrade. While Drupal 9 has good support for upgrading from a Drupal 7 site, we should recognize the task is really building a new site and porting the content rather than an “upgrade”. However, one of the outstanding features of Drupal 9 is that future upgrades will be much easier.

Prune. Evaluate if any feature or element can be excluded in your D7 to D9 upgrade. The time saved by not migrating an underused feature might help offset the costs elsewhere.

Flexibility. Be flexible in what must stay the same and what can change in order to maximize your progress/effort ratio.

New stack, new patterns. Drupal 7 is a monolith of code, while Drupal 9 is an amalgamation of established patterns and popular technologies. Understanding that you now have a completely new stack of technologies (Symphony, Twig, etc.) bound together with the new Drupal 9 framework will help you make better decisions on the upgrade process. Some Drupal 7 patterns became anti-patterns in Drupal 9.

Budget & Timeline. Since you will be rebuilding a lot of your website in Drupal 9, it often makes sense to upgrade the user experience and design at the same time. This can be a great opportunity to evaluate analytics and the lessons learned, since you launched your Drupal 7 website, to guide the new design. However, this will likely increase the budget and extend the timeline.

Timing. Don’t wait too long to start planning for the upgrade. The closer we get to Drupal 7’s end of life in November 2023, the harder it will be to schedule a quality upgrade.


What is the most challenging aspect of a Drupal 7 to Drupal 9 upgrade?


Custom module upgrades. The architecture of Drupal 9 is fundamentally different from previous versions, which requires most aspects of custom modules to be rewritten for compatibility. Drupal 9 has more rigorous control over the organization of the source code, which, at the same time, provides an opportunity to better organize custom code. For example, code related to a specific form needs to live in a dedicated file. Such code organization promotes more efficient development and maintenance.

Contrib module upgrades. There are numerous contributed modules whose upgrade paths are not straightforward. Some modules may have a Drupal 9 release, but its functionality may have changed slightly, which might make it unsuitable for the specific purpose for which a given site relied on it. Some other modules may not have a Drupal 9 release, in which case the related functionality would need to be implemented by either using another, similar contributed module or building a custom solution.

Data migration. Drupal 9 ships with the Migrate module, which can take care of migrating data related to core functionality, such as user and node entities. However, some contrib modules, even though they may have been released for Drupal 9, do not provide an upgrade path to migrate their data over. This might necessitate a custom migration procedure in order to bring the data over to Drupal 9.

Theming. Drupal 7 and Drupal 9 themes are completely different. Porting the theme can’t be automated; You must rebuild it from scratch. There are some resources such as CSS and Javascript files that you can port over. Template files and the theme layer will need to be recreated. Be flexible in giving up old UX patterns and adopting new UX patterns. Treat this as an opportunity to refresh the visual appearance of your website.


What should the client or project manager do to prepare for the upgrade?


Inventory the Drupal 7 site. Perform a thorough inventory of the features and functionality that are required for the Drupal 9 website. Due to changes in Drupal and contrib modules, some features may behave in an unexpected way after the upgrade. The requirements should specify whether these features are available in Drupal 9 and the corresponding contrib modules, or if they will need to be recreated to match the previous functionality

Optimize your site. Take this opportunity to simplify or optimize your site! Review your analytics and user data from the last year and see what call to action you want to focus on in a new design and user experience.

Content type, role and feature audit. Now is the time to discontinue old features, roles, and content types. Many Drupal upgrade projects suffer from simply migrating content types because the content type was previously there, not because it was needed. Evaluate which features no longer add value to your website. Consider replacing these with new or improved features using Drupal 9 contributed modules.

Contrib module cleanup. Identify all contributed modules that are installed. Check if Drupal 9 versions are available, or if you can replace them with something new before starting the migration.

Check known issues. Investigate "Known Issues" for Drupal 7 to Drupal 9 migrations. There are some specific upgrade issues that other websites have already faced and solved. These are usually documented as "Known Issues".


Any other advice you'd offer around a Drupal 7 to Drupal 9 upgrade?


Consider a new contrib module. If there is any custom-built functionality on the site that may be relevant to other sites, they may consider turning that feature into a contrib module and contribute it to the Drupal community. Sorting out a feature into a standalone module may require a larger initial investment in terms of effort, but the potential benefit is that once it has been published, the community may contribute enhancements back to the module.

Module obsolescence. Some Drupal 7 modules may become completely obsolete in Drupal 9. 

Migration Tips. Set up a secondary database with that of Drupal 7 as a data migration source. Try the migration from Drupal 7 to Drupal 9 in iteration until you get it right. Break down your migration into very well defined steps and create backups along the way after each successful step. 

Dealing with deprecated modules. When modules or functionality is deprecated in Drupal, there is often a posted proposal or comment thread that identifies alternate solutions. In the case of the Field Collections module, a proposal is available on the module page that outlines the reasons for deciding to deprecate the module. The proposal also identifies potential replacements for Field Collections, to migrate existing content to the Paragraphs module, and provides a discussion thread with further tips and insights. Don't forget to look to the community for guidance and proposed solutions when challenges arise during the Drupal 9 upgrade process.  


Special thanks to Gergely Lekli, Ki Kim, Lehel Matyus, Mark Etter and Mark Dischler for these tips.