Drupal 11, released in mid-2024, represents one of the most significant steps forward in the CMS's history. It drops PHP 8.1 minimum support, tightens integration with Symfony 6/7, removes long-deprecated APIs, and delivers a cleaner, more performant developer experience. If you're still running Drupal 9 or 10, now is the time to plan your migration.

This guide covers the full process โ€” from initial audit to post-launch validation โ€” based on our experience migrating 20+ production Drupal sites to Drupal 11 over the past year.

1. Pre-Migration Audit

Before writing a single line of code, you need a complete picture of your current setup. Run the following audit on your existing site:

  • PHP version: Drupal 11 requires PHP 8.3+. Confirm your hosting environment can support it.
  • Contrib module inventory: List every module and check Drupal.org for Drupal 11 compatibility. Many modules have already released D11-compatible versions.
  • Custom module audit: Scan for deprecated API usage using drupal-check or phpstan.
  • Theme compatibility: Confirm your base theme (or subtheme) is D11 compatible. Olivero and Claro ship as D11-ready.
  • Database version: MySQL 8.0+ or MariaDB 10.6+ required.

Run the Upgrade Status module โ€” it generates a detailed compatibility report for every module and theme on your site.

2. Update Dependencies with Composer

Drupal 11 is managed entirely through Composer. Start with a dedicated migration branch:

git checkout -b drupal11-migration
composer require drupal/core-recommended:^11 --no-update
composer require drupal/core-composer-scaffold:^11 --no-update
composer update drupal/core* --with-all-dependencies

Resolve any dependency conflicts methodically โ€” don't try to update everything in one shot. Update Drupal core first, then contrib modules one at a time.

3. Handle Breaking Changes

Drupal 11 removes several APIs that were deprecated in Drupal 9 and 10. The most commonly encountered breaking changes include:

  • Removal of \Drupal\Component\Utility\SafeMarkup (use Markup::create())
  • jQuery Update module is no longer required โ€” jQuery 3.7 ships with core
  • CKEditor 4 removed; CKEditor 5 is the only supported editor
  • Deprecated procedural hooks must be converted to OOP-style event subscribers
"The key to a smooth Drupal 11 migration is methodical preparation. 80% of the work happens before you run a single update command."

4. Update Custom Modules and Themes

After resolving core dependency conflicts, turn to your custom code. Use drupal-rector to automatically fix many deprecated API usages:

composer require palantirnet/drupal-rector --dev
vendor/bin/rector process web/modules/custom

Review all changes carefully โ€” automated fixes are a starting point, not a guarantee of correctness.

5. Run Database Updates

drush updatedb
drush config:import
drush cache:rebuild

6. Test Thoroughly Before Launch

  • Automated PHPUnit tests for all custom modules
  • Manual regression testing of all content types and views
  • Editor workflow testing (CKEditor 5 migration is a common sticking point)
  • Performance benchmarking (before vs after)
  • Security scan with drush pm:security

Conclusion

Migrating to Drupal 11 is well worth the investment. Sites we've migrated consistently show 20โ€“40% faster page load times and dramatically reduced technical debt. Start with the pre-migration audit, work through dependencies systematically, and always migrate on a staging environment first.

If you'd like help planning or executing a Drupal 11 migration, get in touch with our team โ€” we've done this dozens of times and can help you avoid the common pitfalls.