Upgrade from Drupal 10 to Drupal 11: A Step-by-Step Guide

Why Upgrade to Drupal 11?

Before diving into the steps, let’s explore why upgrading matters. Drupal 11 offers:

• Enhanced Security: Stricter API access controls and automatic updates keep your site safer.
• Better Performance: Optimized caching and faster database queries mean quicker page loads.
• Modern Features: Updates like CKEditor 5’s autoformatting, Symfony 7, and single directory components (SDC) make content management and development easier.
• Future-Proofing: Drupal 10 support ends in mid-2026, so upgrading now keeps you ahead.

Step 1: Prepare Your Site

Preparation is key to a smooth upgrade. Here’s what to do:

• Back Up Everything: Save your codebase, database, and files using tools like Drush (drush sql-dump) or your hosting provider’s backup feature. Test the backup to ensure it’s restorable.
• Update to Drupal 10.3+: Drupal 11 requires at least Drupal 10.3.0. Run composer update drupal/core-recommended --with-dependencies to update.
• Check Hosting Requirements: Ensure PHP 8.3+, MySQL 8.0+, MariaDB 10.6+, or PostgreSQL 16+. Note that Microsoft IIS is not supported.
• Audit Your Site: Remove unused modules, themes, or content to streamline the process.

Step 2: Check Module and Theme Compatibility

Drupal 11 removes deprecated modules and updates dependencies. Ensure compatibility with these steps:

• Install Upgrade Status Module: Use composer require drupal/upgrade_status and run drush upgrade_status:analyze. Check the report at Admin > Reports > Upgrade Status.
• Update Contributed Modules: Run composer update and verify module compatibility on Drupal.org.
• Review Custom Code: Use Drupal Rector (composer require --dev palantirnet/drupal-rector) to fix deprecated code.
• Handle Removed Modules: Install contributed versions of removed core modules (e.g., Statistics) to preserve functionality.

Step 3: Set Up a Staging Environment

Never upgrade on a live site. Create a staging environment:

• Clone Your Site: Copy your codebase and database to a separate server or local environment.
• Test Functionality: Ensure all features work as expected before proceeding.

Step 4: Perform the Upgrade

With your site prepped, follow these steps:

1. Grant Write Permissions:
    

   chmod 777 web/sites/default
   chmod 666 web/sites/default/*settings.php
   chmod 666 web/sites/default/*services.yml

2. Update Core with Composer:
    

   composer require 'drupal/core-recommended:^11' 'drupal/core-composer-scaffold:^11' 'drupal/core-project-message:^11' --no-update
   composer require 'drush/drush:^13' --no-update
   composer update

3. Run Database Updates:
    

   drush updb -y
   drush cr -y

4. Export Configuration:
    

   drush cex -y

5. Revert File Permissions:
    

   chmod 755 web/sites/default
   chmod 644 web/sites/default/*settings.php
   chmod 644 web/sites/default/*services.yml

Step 5: Test Thoroughly

Test your site in the staging environment:

• Check key functionalities (forms, views, content types).
• Verify custom and contributed modules.
• Test across browsers and devices.
• Review the status report (Admin > Reports > Status) for errors.

Step 6: Deploy to Production

Once tested, deploy to production:

• Back up your production site.
• Deploy the updated codebase and database.
• Run drush updb -y and drush cr -y.
• Monitor for issues.

Troubleshooting Tips

• Composer Errors: Use composer why-not drupal/core 11.0.0 to identify dependency issues.
• Missing Modules: Install contributed versions of removed core modules.
• Custom Code Issues: Check module issue queues or Drupal forums for manual fixes.
• Performance Hiccups: Optimize caching settings post-upgrade.

Final Thoughts

Upgrading from Drupal 10 to 11 is manageable with careful planning. By updating to Drupal 10.3+, auditing modules, fixing code, and testing thoroughly, you’ll minimize risks. The result? A faster, more secure site ready for Drupal 11’s modern features.

Need more tips on securing your Drupal site? Explore our security guide to keep your site safe post-upgrade.

Have questions or tips about Drupal upgrades? Share them in the comments below!