Key Takeaways
- Drupal 9 is built from Drupal 8 with deprecated code removed — it's not a ground-up rewrite, making the upgrade more manageable than previous major versions.
- Drupal 8 reaches end-of-life November 2, 2021 — security updates stop after this date.
- The Upgrade Status module is the essential first step — it identifies all blocking issues before upgrade planning.
- PHP version is a common upgrade blocker — Drupal 9 requires PHP 7.4+, while Drupal 8 supported PHP 7.0.
- Contributed modules must have Drupal 9 compatible releases before upgrading — check drupal.org/project/[module] for D9 compatibility status.
Drupal 9 launched on June 3, 2020 — and with it, Drupal 8 received its end-of-life date: November 2, 2021. For organisations running Drupal 8, this creates a clear timeline for upgrading. Unlike previous major Drupal version migrations — which required migrating content and rebuilding functionality — the Drupal 8 to 9 upgrade is designed to be a relatively smooth in-place upgrade. This design choice was intentional. Drupal 9 was built inside Drupal 8 — the APIs and architecture are the same, with deprecated code removed and major third-party dependencies (Symfony, Twig) updated to their latest versions. Sites that kept pace with Drupal 8 deprecation notices throughout the 8.x release cycle should have minimal upgrade work. Sites that deferred maintenance and accumulated deprecated code usage have more work to do. This guide covers what Drupal 9 changes, how to assess your site's upgrade readiness, and what the upgrade process involves.
Definition: Deprecated API and What It Means for Drupal Upgrades
A Deprecated API is a function, class, or method that still exists in the current version of the software but is scheduled for removal in a future version. Drupal 8 included many deprecated APIs — functions and classes carried over from earlier versions that were marked for removal in Drupal 9. Throughout the Drupal 8 release cycle, the Drupal community produced replacement APIs and updated documentation encouraging developers to migrate away from deprecated usage. Drupal 9 removed these deprecated APIs — code that called deprecated functions in Drupal 8 generates PHP errors in Drupal 9. The Drupal Rector tool (drupal.org/project/drupal_rector) uses automated code refactoring to update many deprecated API usages to their Drupal 9 equivalents — significantly reducing manual custom module update work.
Assessing Your Drupal 8 Site's Upgrade Readiness
The Upgrade Status module produces a comprehensive readiness report — the severity of its findings determines your upgrade timeline and effort.
Install the Upgrade Status module (drupal/upgrade_status) on your Drupal 8 staging environment: `composer require drupal/upgrade_status`, then enable it in the module admin and navigate to Admin > Reports > Upgrade Status. The report checks: all installed contributed modules for Drupal 9 compatible releases (green = compatible, yellow = needs update, red = no D9 version available), all custom modules and themes for deprecated API usage (the more red items, the more custom code work required), and any third-party libraries or JavaScript that may need updates.
Contributed module compatibility is often the most variable factor. For popular modules (Views, Webform, Pathauto, Metatag, Token, Admin Toolbar), Drupal 9 compatible releases have been available for months ahead of the D9 launch. For less common contributed modules — particularly those with small maintainer teams or those solving niche use cases — D9 compatible releases may be delayed or unavailable. Where a D9-compatible release doesn't exist, options are: wait for the port (check the module's issue queue for D9 port progress), fund the port (the Drupal community supports sponsored module development), find an alternative module with the same functionality, or replace the module functionality with custom code.
PHP version compatibility is a frequently overlooked upgrade blocker. Drupal 9 requires PHP 7.4 as a minimum (and supports PHP 8.0+). Drupal 8 supported PHP 7.0, 7.1, 7.2, and 7.3 — sites on older hosting environments running PHP 7.2 or 7.3 need a PHP upgrade before upgrading Drupal. Check your current PHP version in Drupal Admin > Reports > Status Report. If your hosting environment doesn't support PHP 7.4 or 8.0, a hosting upgrade or migration may be required as part of the D9 upgrade project.
- Install Upgrade Status module on staging — do not run on production
- Check contributed module D9 compatibility — drupal.org/project/upgrade_status covers all installed modules
- Check PHP version — Drupal 9 requires 7.4 minimum, 8.0+ recommended
- Review custom module and theme deprecated API usage — the most variable upgrade effort factor
- Run Drupal Rector on custom code — automates many deprecated API replacements
The Drupal 8 to 9 Upgrade Process
The upgrade sequence: update D8 to latest minor version, fix all deprecated API usage, update composer dependencies, run the upgrade, and verify functionality on staging before production deployment.
Step 1: Update Drupal 8 core to the latest 8.9.x release (the final Drupal 8 minor version, maintained until D8 EOL). Run `composer update drupal/core-recommended drupal/core-composer-scaffold --with-all-dependencies` to update core and all dependencies. Then update all contributed modules to their latest 8.x releases — many latest 8.x module releases are also compatible with Drupal 9, so this step pre-resolves some D9 compatibility issues.
Step 2: Fix deprecated API usage. Install the Drupal Rector tool and run it against your custom modules: `vendor/bin/rector process web/modules/custom`. Rector applies automated fixes for many common deprecated usages. Review the changes it makes and test that custom module functionality still works after the automated refactoring. For remaining deprecated usages that Rector doesn't handle, update manually following the deprecation notices (Drupal.org deprecation notices include the recommended replacement for each deprecated function).
Step 3: Upgrade Drupal core from 8.x to 9.x by updating the composer.json version constraint and running composer update. On staging, run `drush updb` to apply any database updates. Run `drush cr` to rebuild caches. Verify all pages load without PHP errors, all contributed modules function correctly, and custom functionality is intact. Run your full test suite if you have one. After staging verification is complete, deploy to production during a maintenance window.
Experience Signal
The Drupal 8 to 9 upgrades that go smoothest are the ones on sites that maintained Drupal core and contributed module updates throughout the 8.x release cycle — sites that ran the latest 8.x minor releases had already resolved many deprecation warnings progressively, making the final D9 upgrade a minor step. The more challenging upgrades are on sites that went 12–18 months without core updates and have accumulated multiple version gaps in contributed modules, plus significant deprecated API usage in custom code that was never addressed. The lesson: ongoing maintenance is significantly less expensive than deferred major version upgrades.
Frequently Asked Questions
The Drupal 8 to 9 upgrade is significantly less disruptive than previous major version migrations (Drupal 6 to 7, or 7 to 8) because Drupal 9 was built into Drupal 8 — it's essentially Drupal 8 with deprecated code removed and third-party dependencies updated (Symfony 4/5 instead of Symfony 3, Twig 2/3 instead of Twig 1). For a Drupal 8 site with: up-to-date core, all contributed modules compatible with Drupal 9, and no deprecated API usage in custom code, the upgrade can be straightforward. For sites with custom modules using deprecated APIs or contributed modules not yet ported to Drupal 9, the upgrade involves fixing or replacing that code before upgrading.
After November 2, 2021 (Drupal 8 end-of-life), Drupal 8 no longer receives security updates, bug fixes, or new features from the Drupal security team and core development community. Sites running Drupal 8 after that date continue to function — EOL doesn't 'turn off' anything — but they accumulate security risk as new vulnerabilities are discovered without patches. This is the same pattern as Drupal 7 (EOL November 2022) and WordPress sites running outdated versions. Organisations with data security compliance requirements (PCI DSS, HIPAA, SOC 2) may be required to run supported software versions, making Drupal 8 EOL a compliance issue as well as a security issue.
The Upgrade Status module (drupal.org/project/upgrade_status) scans your Drupal 8 site and reports: which contributed modules have Drupal 9 compatible releases, which have deprecated API usage, which custom modules or themes use deprecated code, and which third-party libraries need updating. Run this module on your staging environment before planning your upgrade timeline. The report categorises issues by severity — some are blockers (must be fixed before upgrade), some are warnings (should be fixed after upgrade), and some are informational. The number of blocking issues determines how much preparation work the upgrade requires.
Sources
Running Drupal 8 and Need to Upgrade?
Webnixon manages Drupal 8 to 9 upgrades — from Upgrade Status assessment through deprecated API remediation, contributed module updates, and production deployment with full functionality verification.
Book a Drupal Upgrade ConsultationAbout the author
David Okafor
Developer
David is a full-stack developer at Webnixon with expertise in React, WordPress, and custom web application development. He contributes to complex front-end builds, API integrations, and performance-focused engineering for Webnixon clients. He writes about web development best practices, WordPress, and the technical side of building fast, maintainable websites.
Related Articles
Web Design
Why Enterprises and Governments Choose Drupal: A Business Decision Guide
Drupal is used by the White House, NASA, the University of Oxford, and thousands of government and enterprise organisations worldwide. It's not the easiest content management system to build with — but for organisations with complex content structures, strict security requirements, and high scalability demands, it's frequently the most capable option available.
Web Design
Drupal vs WordPress: Which CMS Is Right for Your Organisation?
WordPress and Drupal are the two most widely deployed open-source CMS platforms in the world. WordPress powers over 33% of all websites. Drupal is the CMS of choice for governments, universities, and enterprise organisations with complex content requirements. Here's how to choose between them.
Web Design
Website Accessibility: What WCAG 2.1 Means for Your Business Website
Web accessibility — designing websites so that people with disabilities can use them — is a legal requirement in Canada, the EU, and parts of the US, and increasingly a procurement requirement in enterprise and government RFPs. Here's what WCAG 2.1 requires and how to audit your website against it.