Upgrading from Drupal 9 to Drupal 11: What’s New, What Breaks, and How to Migrate Smoothly ⚙️

Drupal 11 is here, and if you're still on Drupal 9, it's time to get moving. With new improvements in performance, Symfony versioning, CKEditor 5, and better APIs — this upgrade is essential for keeping your site fast, secure, and modern. Let’s walk through how to prepare and upgrade your project without breaking things.

🧭 Why Upgrade from Drupal 9 to 11?

• Drupal 9 is End-of-Life: Security updates will stop. Don’t risk it.
• Drupal 11 = Faster: Performance boost, cleaner core.
• Symfony 6.3+ and PHP 8.2+ compatibility.
• CKEditor 5 replaces CKEditor 4. Huge editor improvements.
• Deprecated APIs removed — your code stays cleaner and future-proof.

🧼 Step 1: Clean Up Your Drupal 9 Site

Before anything, clean up your project. Remove unused modules, themes, and deprecated code. Use:

composer outdated drupal/*

Then update your contrib modules:

composer update drupal/[module_name]

🧪 Step 2: Run Upgrade Status Check

Install and run the Upgrade Status module. It will scan your current setup and tell you if:

• Your PHP version is compatible
• Modules are ready for Drupal 11
• Your custom code needs refactoring

🔍 Step 3: Check for Deprecated Code

Use Drupal Rector or phpstan-drupal to check for deprecated APIs and functions.

If you used drupal_set_message(), config_get(), or similar — it needs replacement.

🧱 Step 4: Test Custom Modules and Themes

Custom modules and themes must be updated to match Drupal 11 API standards. Focus on:

• Theme YAML compatibility
• Module service injection syntax
• Routing and form builder changes

🔄 Step 5: Update Core and Dependencies

If you're ready, update your core using Composer:

composer require 'drupal/core-recommended:^11' 'drupal/core-composer-scaffold:^11' 'drupal/core-project-message:^11' --update-with-dependencies

Then clear cache:

drush cr

🚧 Step 6: Test Everything Thoroughly

Now run:

• Functional Testing: Forms, content creation, search, login
• Theming Checks: Layout, blocks, menu structures
• Permission Audits: Ensure roles and access controls work

🧠 Bonus Tip: Use a Staging Environment

Never upgrade on your live server. Set up a clone of your Drupal 9 site, test the migration, fix the issues, then push to production when fully verified.