Upgrading from Drupal 9 to Drupal 10: A Step-By-Step Guide

Upgrading from Drupal 9 to Drupal 10: A Step-By-Step Guide

If you work with Drupal, you know it constantly evolves to meet the changing demands of modern web development and to remain one of the highest performing content management systems. These continual changes require upgrades to ensure security, performance, and compatibility with the latest technologies. 

After we recently upgraded from Drupal 9 to Drupal 10, we thought a step-by-step guide would help provide other devs and internal tech teams a better idea of what to expect and how to troubleshoot if something goes wrong.

Step 1: Evaluating Compatibility

Before initiating the upgrade, make sure you and your team have assessed your project's compatibility with Drupal 10. You can do this using the following commands:

composer why-not drupal/core 10.*composer update 'drupal/core-* --with-all-dependencies --dry-run'

These commands will provide insights into the reasons why the latest Drupal 10 version may not install and offer a preview of the changes without affecting your current setup.

Step 2: Upgrading Core, Modules, and Themes

Start by updating your project's Drupal Core to the latest version within the current major release and then update each module and theme to their respective Drupal 10 versions. If these versions are unavailable, seek alternatives, create patches, or explore contributed solutions to ensure compatibility. Then, address any requirements indicated in the why-not list during the update process. After updating the modules and installing the necessary requirements, be sure to verify the absence of available updates in /admin/reports/updates to confirm the successful completion of this step.

Step 3: Managing Deprecated Components

Drupal 10 deprecates several core modules and themes, and managing these are essential for a seamless transition. Some of these components include:

Deprecated Modules

• Aggregator
• CKEditor (consider migrating to CKEditor 5)
• Color
• HAL
• Quick Edit
• RDF

Deprecated Themes

• Bartik (consider utilizing the contributed project for Bartik)
• Classy (explore the provided alternative for Drupal 10)
• Seven (consider transitioning to Claro or Gin for administrative purposes)
• Stable (refer to the available project for Drupal 10)

Step 4: Updating Configuration Files

When you’re ready to update configuration files, you can streamline the process by making a few necessary adjustments. Delete the composer.lock file and the vendor folder from the project root. The system will automatically regenerate these files upon successful implementation.

Next, update all custom modules and themes in the  module_name.info.yml and theme_name.info.yml files to include the core_version_requirement: ^9 || ^10 directive. This step ensures compatibility with both Drupal 9 and 10.

Step 5: Composer Update and Dependency Resolution

You can use the below command to execute the following composer update command and install Drupal 10:

composer require drupal/core-recommended:10.1.5 drupal/core-composer-scaffold:10.1.5 drupal/core-project-message:10.1.5 --update-with-all-dependencies

The command might display dependency errors, as shown in the sample error list below:

Your requirements could not be resolved to an installable set of packages.

Problem 1

- symfony/process[v4.4.0-BETA1, ..., v4.4.10] require php ^7.1.3 -> your php version (8.1; overridden via config.platform, actual: 8.1.16) does not satisfy that requirement.- Root composer.json requires drupal/console-core ^1.9.8 -> satisfiable by drupal/console-core[1.9.8].- drupal/console-core 1.9.8 requires symfony/process ~3.0|^4.4 -> satisfiable by symfony/process[v3.0.0-BETA1, ..., 3.4.x-dev, v4.4.0-BETA1, ..., 4.4.x-dev].- You can only install one version of a package, so only one of these can be installed: symfony/process[v2.1.0, ..., 2.8.x-dev, v3.0.0-BETA1, ..., 3.4.x-dev, v4.0.0-BETA1, ..., 4.4.x-dev, v5.0.0-BETA1, ..., 5.4.x-dev, v6.0.0-BETA1, ..., 6.4.x-dev].- drupal/core-recommended 10.1.5 requires symfony/process ~v6.3.0 -> satisfiable by symfony/process[v6.3.0-BETA1, ..., 6.3.x-dev].- Root composer.json requires drupal/core-recommended 10.1.5 -> satisfiable by drupal/core- recommended[10.1.5].

It’s important to identify and resolve any dependency issues specific to your project—and you might consider removing conflicting packages or versions to meet the required dependencies for Drupal 10.

Step 6: Finalizing the Update

After resolving all dependency errors and completing the Composer update without any issues, you can confirm the successful transition by checking /admin/reports/updates in the Drupal Admin to confirm that your Drupal instance is up-to-date and fully compatible with Drupal 10.

And that’s it. Following these steps will help you seamlessly upgrade your Drupal 9 project to Drupal 10 so you can leverage better performance, security, and compatibility with the latest features and developments within the Drupal ecosystem. Looking for Drupal migration support? Contact us to learn more about what we offer and how our expert web developers can help.