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.

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:

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.

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.

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

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

• 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)

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.

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:

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.

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.