Migrate Like a Pro: Upgrading from Drupal 9 to Drupal 10 Smoothly

Drupal 9 reached end-of-life in November 2023, meaning no further security patches, bug fixes, or community support. Organisations still running Drupal 9 face increasing security vulnerabilities, incompatibility with modern PHP versions, and a growing gap from contributed module updates.

Drupal 10 delivers substantial improvements: the Olivero default theme for modern, accessible design; CKEditor 5 replacing CKEditor 4 for richer content editing; Symfony 6.4 for improved performance and long-term support; PHP 8.1+ requirement enabling modern language features; and a streamlined codebase with legacy deprecated code removed.

This guide provides a step-by-step migration roadmap — from pre-upgrade audit through post-upgrade SEO validation — based on MDS's experience migrating enterprise Drupal sites across healthcare, finance, and government sectors.

Before touching code, conduct a thorough compatibility audit to identify blockers:

• Upgrade Status Module: Install drupal/upgrade_status and run a full scan of core, contributed, and custom modules. The module reports deprecated API usage, incompatible dependencies, and missing Drupal 10-compatible releases.
• PHP Version Check: Drupal 10 requires PHP 8.1 minimum (8.2+ recommended). Verify your hosting environment supports this — legacy PHP 7.4 or 8.0 environments must be upgraded first.
• Contributed Module Audit: Check every contributed module at drupal.org/project/{module}/releases for a Drupal 10-compatible release. Identify modules without Drupal 10 support — these need alternatives or custom patches.
• Custom Code Scan: Run phpstan with Drupal deprecation rules to identify deprecated function calls, removed APIs, and code patterns that won't work in Drupal 10.
• Database Backup: Create a full backup of the database, files directory, and composer.lock before any changes. Verify backup restoration works in a staging environment.

The audit typically reveals 10-30 issues for enterprise sites — MDS categorises these as critical blockers, warnings, and informational to prioritise remediation.

Drupal 10 migration is a Composer-driven process:

• Step 1 — Update to Latest Drupal 9: Before upgrading to 10, ensure you're on the latest Drupal 9.5.x release. Run composer update drupal/core-recommended --with-dependencies and drush updatedb.
• Step 2 — Resolve Deprecations: Address all deprecation warnings identified by the Upgrade Status module. Update contributed modules to their latest 9.x versions that declare Drupal 10 compatibility.
• Step 3 — Update composer.json: Change drupal/core-recommended constraint from ^9 to ^10. Update drupal/core-composer-scaffold and drupal/core-project-message similarly.
• Step 4 — Execute Composer Update: Run composer update drupal/core-* --with-dependencies. Resolve any dependency conflicts — common issues include contributed modules pinned to Drupal 9-only versions.
• Step 5 — Database Updates: Run drush updatedb -y followed by drush cache:rebuild to apply schema changes and clear cached definitions.

For sites using Composer patches (cweagans/composer-patches), verify all patches still apply cleanly to Drupal 10 core — many patches are already included in core.

Drupal Rector automates the most tedious part of migration — fixing deprecated code in custom modules and themes:

• Installation: Add palantirnet/drupal-rector to your project's dev dependencies. Configure rector.php with the Drupal-specific rule sets for your target version.
• Automated Fixes: Rector automatically replaces deprecated function calls (e.g., drupal_set_message() → \Drupal::messenger()->addMessage()), updates hook implementations, and refactors service container calls.
• Preview Mode: Run vendor/bin/rector process --dry-run first to review all proposed changes without modifying files. Inspect the diff output for accuracy before applying.
• Manual Review: Rector handles ~70-80% of deprecated code automatically. Remaining issues require manual intervention — complex dependency injection refactoring, event subscriber migrations, and custom plugin alterations.

After Rector processing, run phpcs --standard=Drupal,DrupalPractice to ensure all code meets Drupal coding standards and phpstan for static analysis compliance.

Theme migration is often the most visible change in the Drupal 10 upgrade:

• CKEditor 5 Migration: CKEditor 4 is completely removed in Drupal 10. Use the built-in CKEditor 5 migration tool to convert text format configurations. Custom CKEditor 4 plugins need rewriting as CKEditor 5 plugins using the new plugin architecture.
• Olivero Default Theme: The new Olivero theme replaces Bartik as the default frontend theme. For sites using Bartik-based custom themes, retheme against Olivero or maintain Bartik as a contributed module (drupal/bartik).
• Claro Admin Theme: Claro replaces Seven as the default admin theme, providing a modern, accessible admin interface with improved form layouts and navigation.
• Twig 3 Updates: Drupal 10 uses Twig 3 (via Symfony 6). Review custom Twig templates for deprecated filters, functions, and syntax — most changes are minor but must be addressed.
• CSS/JS Libraries: jQuery UI is removed from core. Custom themes depending on jQuery UI widgets (accordion, datepicker, sortable) need alternatives — either include jQuery UI as a library or migrate to vanilla JavaScript.

MDS recommends treating theme migration as an opportunity for design refresh — combining the Drupal 10 upgrade with a modern design system implementation.

Migration without SEO preservation can devastate organic traffic. Protect your search rankings with these practices:

• URL Structure: Maintain identical URL patterns using the Pathauto module. If URL aliases change, implement 301 redirects using the Redirect module with bulk redirect import for large sites.
• Meta Tags: Export and verify all meta tag configurations using the Metatag module. Ensure title tags, meta descriptions, canonical URLs, and Open Graph tags remain intact after migration.
• Structured Data: Validate JSON-LD structured data (Schema.org markup) using Google's Rich Results Test pre and post-migration. Common schema types to verify include Organisation, BreadcrumbList, Article, and FAQPage.
• XML Sitemaps: Regenerate XML sitemaps using the Simple Sitemap module and resubmit to Google Search Console and Bing Webmaster Tools.
• Robots.txt: Verify robots.txt (managed by Drupal's scaffold) allows crawling of all intended pages. Ensure staging environments are blocked from indexing during migration testing.

MDS performs pre and post-migration SEO audits using Screaming Frog and Google Search Console, tracking indexed pages, crawl errors, and Core Web Vitals metrics.

Drupal 10's Symfony 6 foundation delivers inherent performance improvements — maximise them with targeted tuning:

• Dynamic Page Cache: Enable the Dynamic Page Cache module for authenticated users. This caches page fragments based on user permissions, dramatically reducing database queries for logged-in users.
• BigPipe: Enable the BigPipe module to stream page content in chunks — the page layout renders immediately while personalised blocks load asynchronously.
• CSS/JS Aggregation: Enable aggregation in /admin/config/development/performance to combine and minify CSS/JS files, reducing HTTP requests and improving LCP (Largest Contentful Paint).
• Redis/Memcached: Replace the default database cache backend with Redis (drupal/redis) or Memcached for 5-10x faster cache reads, especially on high-traffic sites.
• PHP OPcache: Tune PHP OPcache settings — increase opcache.memory_consumption to 256MB+ for enterprise sites and enable opcache.preload with Drupal's preload script for faster bootstrap.

After tuning, validate Core Web Vitals (LCP < 2.5s, FID < 100ms, CLS < 0.1) using Lighthouse and Google PageSpeed Insights.

A successful Drupal 10 migration requires comprehensive post-upgrade testing:

• Functional Testing: Verify all content types, views, forms, user registration, and custom functionality work as expected. Use automated testing tools (Behat, PHPUnit) for regression testing.
• Visual Regression: Use tools like BackstopJS to compare screenshots of key pages pre and post-migration, catching CSS regressions that functional tests miss.
• Performance Baseline: Run Lighthouse audits on 10+ representative pages and compare against pre-migration baselines. Flag any regressions > 10%.
• Security Scan: Run Drupal's built-in security review (drupal/security_review) and external scanners to verify no new vulnerabilities were introduced during migration.

MetaDesign Solutions has migrated 50+ enterprise Drupal sites from Drupal 7/8/9 to Drupal 10, including government portals, healthcare platforms, and e-commerce sites with millions of pages. Contact us for a migration assessment and timeline estimate.