How to upgrade from Drupal 10 to Drupal 11

Drupal version compatibility

• Target version: Drupal 11.x
• Minimum source version: Drupal 10.3.x

Prerequisites

Before beginning the upgrade, ensure your environment and site meet the following requirements:

• Hosting environment: Must meet Drupal 11 platform requirements.
• Current version: Site must be running Drupal 10.3.0 or later. All core updates prior to 10.3.0 have been removed in Drupal 11.
  • Learn how to update Drupal
  • Check out deprecated and obsolete extensions
• Access: Command-line access with Composer and Drush installed.
• Permissions: Ability to modify file permissions (chmod) on the server.
• PHP: 8.3.0 or later.

1. Prepare for upgrade

Manage scaffold files and deprecations

All Drupal core files (including .htaccess) will change. If you have customized scaffold files, document your changes to reapply them later.

• Example: Drupal 11 removed the Statistics module. If you have custom Statistics rules in .htaccess, they should be removed as the contributed module now handles its own protection.

Resolve core modules and themes

Several modules are deprecated in Drupal 10 and removed in Drupal 11:

• Removed extensions: Actions UI, Activity Tracker, Book, Forum, Statistics, and Tour.
• Obsolete extensions: Single Directory Components (SDC) and Help Topics (functionality moved to core).

Options for handling removed modules:

1. Stop using the module in Drupal 10 before upgrading.
2. Install the contributed version of the module in Drupal 10.3+ before performing the Drupal 11 code upgrade.

2. Update contributed & custom code

Check compatibility with upgrade status

Use the Upgrade Status module to identify compatibility gaps.

To update a module to a specific version (e.g., drupal/webform), run:

composer require drupal/webform:^6.2 --no-update

If a compatible version isn't found:

• Check the module's issue queue for Drupal 11 patches. Read "Create a Drupal 11 compatibility patch" for more tips.
• Use the Drupal Lenient Composer endpoint for modules requiring patches.
• Multi-version compatibility: You can allow multiple versions in composer.json to bridge the gap. For example, change "drupal/linkit": "^6.1" to "drupal/linkit": "^6.1 || ^7.0"

Note: If a module requires manual checking, patches, or community collaboration, see Incompatible Contributed Modules in the Appendix.

Update custom code

Use Drupal Rector and Upgrade Status to replace code deprecated in Drupal 10.

Cleanup (optional)

Once compatibility is confirmed, you may remove Upgrade Status and Drush (reinstalling Drush after the upgrade):

drush pm:uninstall upgrade_status -y
composer remove drupal/upgrade_status --no-update

3. Perform the upgrade to Drupal 11

Execute these steps from the Drupal root directory.

Step 1: Open file permissions

chmod u+w web/sites/default
chmod u+w web/sites/default/*settings.php
chmod u+w web/sites/default/*services.yml

Step 2: Update core dependencies

We use --no-update to prevent dependency conflicts while preparing the requirements.

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

If drupal/core is listed explicitly in your composer.json, remove it:

composer remove drupal/core --no-update

Update development tools and Drush:

composer require 'drupal/core-dev:^11' --dev --no-update
composer require 'drush/drush:^13' --no-update

Step 3: Run the update

First, perform a dry run to check for errors:

composer update --dry-run

If successful, execute the actual update:

composer update

Note: To update only core and Drush, use:

composer update "drupal/core-*" drush/drush --with-all-dependencies

Step 4: Verify and database update

Ensure the environment is consistent:

composer install

Run pending database updates:

drush updatedb:status
drush updatedb

Step 5: Restore permissions

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

4. Post-upgrade tasks

1. Export configuration: Upgrades often change configuration schema or ordering: drush config:export
2. Code standards: Run PHP CodeSniffer to align with Drupal 11 coding standards.
3. Testing:
   • Run automated tests (PHPUnit/Behat).
   • Monitor logs while browsing: drush watchdog:tail
   • Run cron: drush cron

Legacy & appendix

Incompatible contributed modules

If Upgrade Status reports contributed modules that are not yet compatible with Drupal 11, there are a few possible paths forward:

• Manual verification: Upgrade Status is helpful but not perfect. Manually check if there are Drupal 11 compatible versions that the report may not identify. Require the module via Composer explicitly:
  

  composer require drupal/MODULE_NAME:^VERSION --no-update

• Apply patches: Look in the module project issue queue for a patch that provides compatibility. Refer to the Lenient Composer documentation for details on handling version constraints that are only patched locally.
• Cooperate with maintainers: If no version or patch exists, check the module's project page for Drupal 11 plans. You can offer help or refer to Create a Drupal 11 compatibility patch for tips.

Common issues

• Dependency resolution failures: If composer update fails, try resetting all constraints: composer show --no-dev --direct --name-only | xargs composer require --no-update
• Identifying blockers: composer why-not drupal/core ^11
• Broken patches: If using cweagans/composer-patches, check if patches were merged into core or need updated versions for Drupal 11.
• Lock file warnings: If the lock file is out of sync, delete composer.lock and the vendor folder, then run composer update.

Support resources

• Project update working group (PUWG): Join the #project-update-working-group channel on Drupal Slack or visit the PUWG project page.
• Upgrade to Drupal 11 on Drupalize.me.