Drupal 11 Upgrade Guide: Essential Steps for a Smooth Transition

Profile picture for user Ahmad Halah
Ahmad Halah

Share

Drupal 11 is on the horizon, and while it may seem early, being prepared is key to a successful upgrade. Thanks to the new Drupal 10 support model, you have until mid-late 2026 to make the transition. However, understanding the upgrade process now can save you time and resources in the future.

This comprehensive guide will walk you through the essential steps to prepare your Drupal site for the upcoming version 11. We'll cover everything from environment readiness to code updates, ensuring a smooth transition for your organization.

 

Why Prepare Early for Drupal 11?

  1. Smooth Transition: Early preparation allows for a more gradual and less disruptive upgrade process.
  2. Resource Management: Spreading the workload over time helps manage resources more effectively.
  3. Risk Mitigation: Identifying potential issues early reduces the risk of critical problems during the upgrade.
  4. Performance Optimization: Drupal 11 brings performance improvements that you can benefit from sooner.

 

The 5-Step Drupal 11 Upgrade Process

To ensure a successful upgrade to Drupal 11, follow these five critical steps:

  1. Prepare your environment for Drupal 11
  2. Update your site to the latest version of Drupal 10
  3. Update all contributed modules to their latest versions
  4. Update custom module code
  5. Upgrade to Drupal 11 core

Let's dive deeper into each of these steps and explore the key considerations for a seamless upgrade.

 

Related: The Ultimate Guide to Drupal 11 CMS Features and Upgrades

 

Step 1: Prepare Your Environment for Drupal 11

Platform Requirements

Before upgrading to Drupal 11, ensure your hosting environment meets the following requirements:

PHP Update
  • Requirement: PHP 8.3 with zlib extension enabled
  • Action: Update your PHP version to 8.3
  • Benefit: PHP 8.3 offers significant performance improvements over earlier versions

 

Database Requirements
  • MySQL: Version 8.0 required
    • Alternative: Use MySQL 5.7 Backport module if unable to upgrade
  • MariaDB: Version 10.6 required
    • Alternative: Use MariaDB 10.3 Backport module if needed
  • PostgreSQL: Version 16 required
  • SQLite: Version 3.45 with json1 extension required

 

Web Server
  • Apache: Version 2.4.7 or greater
  • Note: IIS support has been removed in Drupal 11

 

Key Dependencies

  • Symfony 7
  • jQuery 4
  • PHPUnit 10
  • Composer 2.7.7

 

Drush Update

If you use Drush, update to version 13: 

composer require drush/drush ^13

 

Step 2: Update to the Latest Drupal 10 Version

Before attempting the Drupal 11 upgrade, ensure your site is running on the latest version of Drupal 10. As of now, you should aim for Drupal 10.3.0 or later.

Why this matters: Updating to the latest Drupal 10 version ensures you have all the latest features and security updates, making the transition to Drupal 11 smoother.

 

Step 3: Master the Art of Deprecation Scanning

Identifying and addressing deprecated code is not just crucial—it's the cornerstone of a successful Drupal 11 upgrade. Let's dive into the tools and techniques that will make you a deprecation detective:

 

Unleash the Power of Upgrade Status Module

The Upgrade Status module is your Swiss Army knife for Drupal upgrades. Here's how to wield it effectively:

  1. Install the module: composer require drupal/upgrade_status
  2. Navigate to Reports » Upgrade Status in your Drupal admin panel.
  3. Run a comprehensive scan to uncover:
    • Contributed modules crying out for updates
    • Custom code clinging to deprecated APIs
    • Potential compatibility roadblocks

🔍 Pro Tip: Run the scan in a staging environment that mirrors your production site for the most accurate results.

 

Automate Fixes with Drupal Rector

Drupal Rector is like having a team of developers working tirelessly to update your code. Here's how to put it to work:

  1. Install Drupal Rector: composer require palantirnet/drupal-rector --dev
  2. Generate a configuration file: vendor/bin/rector init
  3. Run Rector on your custom modules: vendor/bin/rector process web/modules/custom

🚀 Rector in Action: In a recent project, Drupal Rector automatically fixed over 60% of deprecation issues, saving hours of manual coding!

 

Leverage the Community with Project Update Bot

The Drupal community is your ally in the upgrade process. The Project Update Bot is their automated scout:

  1. Visit drupal.org and search for your installed modules.
  2. Look for issues tagged with "Drupal 11 compatibility" opened by the bot.
  3. Engage with the community in these issues to stay informed about progress and contribute if possible.

 

Step 4: Update Contributed and Custom Code

Updating Contributed Modules

  1. Use Composer to update modules identified by Upgrade Status.
  2. For modules without Drupal 11 compatible versions:

 

Updating Custom Code

  1. Address all deprecations identified by Upgrade Status and Drupal Rector.
  2. Test thoroughly after each change to ensure functionality is maintained.
  3. Pay special attention to:
    • API changes
    • Function replacements
    • Class and namespace updates

 

Step 5: Perform the Drupal 11 Core Update

Once all preparatory steps are complete, it's time to update Drupal core:

  1. Backup Everything: Create a full backup of your code and database.
  2. Dry Run: Use Composer's dry-run feature to preview the update:

    composer update --dry-run

  3. Resolve Dependencies: If the dry run shows conflicts, use:

    composer why-not drupal/core 11.0 to identify and resolve dependency issues.

  4. Perform the Update: When ready, run:

    composer update drupal/core --with-all-dependencies

  5. Run Database Updates: After updating core, run:

    drush updatedb

  6. Clear Caches: Clear all caches with:

    drush cache:rebuild

  7. Test Thoroughly: Conduct comprehensive testing on your upgraded site.

 

Conclusion

Upgrading to Drupal 11 requires careful planning and execution. By following this guide, you'll be well-prepared to make the transition smoothly. Remember, the key to a successful upgrade lies in early preparation, thorough testing, and staying up-to-date with the latest Drupal developments.

Start your Drupal 11 preparation today, and you'll be ready to leverage its new features and improvements as soon as it's released. Happy upgrading!

 

Author Bio: Ahmad Halah is a seasoned Drupal developer with 10+ years of experience in building Drupal digital experiences.

Drupal 11
Drupal 10
Drupal