Migrating from Drupal 9 to Drupal 10: A Step-by-Step Guide

Just like any software, Drupal releases new versions to improve functionality, security, and overall user experience. Hence, Drupal 9 in June 2020 and Drupal 10 in December 2022, and a number of minor updates before and after. Each of them brings enhancements in performance, accessibility, and developer experience.

Do you have a Drupal website? Then you would want it to be equipped with all the latest advancements in this CMS, and that’s where migrating to Drupal 10 becomes necessary. You can, of course, consult with dedicated Drupal developers to carry out the migration process effectively.

But if you want to complete this process yourself, this guide will come in handy. Let’s begin by discussing the differences between Drupal 9 and 10.

Drupal 9 vs Drupal 10: Comparison Table

FactorDrupal 9Drupal 10
Release DateJune 2020December 2022
PHP VersionSupports 7.3 and aboveRequires 8.0 or above
Symfony FrameworkSymfony 4.4 and aboveSymfony 5.4 or above
Default Administration ThemeSevenClaro (Improved UI/UX)
Default Front-end ThemeBartikOlivero (Modern, WCAG AA compliant)
Rich Text EditorCKEditor 4CKEditor 5 (Improved features, ongoing support)
JavaScript LibraryjQueryAdvanced JS components
Decoupled MenusNot built-inAvailable for more flexible menu management

As you may expect, Drupal 10 is an evolution of Drupal 9, aimed at improving the underlying infrastructure and development process. Although many of the core features are similar between the two versions, there are some significant differences as well. And they have been covered in this table.

Why Migrate from Drupal 9 to Drupal 10?

As you may have understood by now, Drupal 10 is a more evolved version of Drupal 9. So migrating from Drupal 9 to 10 would bring a range of benefits. Let’s take a look.

  • Enhanced Security: Drupal 10 leverages the latest versions of core dependencies like Symfony and CKEditor, which translates to improved security patches and a more robust foundation for your website.
  • Long-term Support: As of November 2023, Drupal 9 has reached its end-of-life, meaning limited security updates will be available. Migrating to Drupal 10 ensures continued security support and access to the latest security fixes.
  • Improved Performance and User Experience: Drupal 10 incorporates enhancements for improving the website performance. It also introduces a new default theme, Olivero, with a focus on accessibility and a modern user interface. This translates to a faster, more user-friendly experience for both website visitors and administrators.
  • Future-proofing: Drupal 10 lays the groundwork for future advancements, particularly in the area of headless Drupal. By migrating now, you position your website to take advantage of these future innovations and maintain a competitive edge.
  • Simplified Development and Maintenance: Drupal 10 streamlines the development and maintenance process with improved tools and functionalities. This can save time and resources for developers working on your website.
  • Cleaner Codebase: Drupal 10 removes deprecated code from Drupal 9, resulting in a cleaner and more efficient codebase. This can improve overall website performance and simplify future maintenance.

While the migration process requires some effort, the benefits outweigh the efforts. You get enhanced security, improved user experience, and access to future advancements. So follow along and migrate from Drupal 9 to Drupal 10. Hiring a dedicated Drupal development company for the same would also be a worthwhile investment for your website’s long-term success.

How to Migrate from Drupal 9 to Drupal 10?

Migration process for any software can be a little tricky. With Drupal, you may have a website running on the Version 9. So how do you make sure of a smooth transition while maintaining the performance and security of the website? That’s why you need a step-by-step process, and it starts from the preparation.


Step 1: Backup

Before starting any migration, create a full backup of your Drupal 9 website, including the database and files. This serves as a safety net in case of unforeseen issues.

Step 2: System Requirements

Drupal 10 has stricter system requirements compared to Drupal 9. Here’s a detailed breakdown of the key requirements to ensure compatibility:

  • PHP Version: Drupal 10 requires PHP version 8.0 or above. Drupal 9, on the other hand, supports PHP versions starting from 7.3.
  • Database: Drupal 10 is compatible with various database management systems, including MySQL, MariaDB, and PostgreSQL. However, ensure your database system is running a version that supports Drupal 10’s requirements.
  • Web Server: Drupal 10 functions with most popular web servers like Apache and Nginx. Verify that your web server meets the necessary PHP version and module dependencies.

Verify that your hosting environment meets the requirements for Drupal 10.

Step 3: Update Contributed Modules and Themes

You need to verify that all contributed modules and themes currently used on your Drupal 9 site are compatible with Drupal 10. Update them to their latest Drupal 10 compatible versions if available. You can use tools like the Upgrade Status module to identify compatibility issues.

Step 4: Update Custom Code

If you have custom modules or themes, review and update them for compatibility with Drupal 10. This may involve addressing deprecated code elements and making necessary adjustments. Tools like Drupal Rector can assist in automating some of these updates.

Upgrade Process

Step 5: Update Drupal Core

Before proceeding to Drupal 10, upgrade your Drupal 9 core to the latest minor version (Like 9.4 or 9.5). It ensures you’re working with the most recent bug fixes and security patches available in Drupal 9. These improvements can contribute to a more stable and secure foundation for your website during the migration process.

Moreover, upgrading to the latest Drupal 9 minor version often lays the groundwork for a smoother upgrade path to Drupal 10. The codebase will be more closely aligned with Drupal 10. That minimizes the number of conflicts or compatibility issues that might arise during the migration itself.

Step 6: Address Deprecated Code

Drupal 10 removes code deprecated in Drupal 9. Use the Upgrade Status module and Drupal Rector tool to identify and address any deprecated code within your custom modules and themes.

Here’s how this part of the process goes:

1. Run Upgrade Status Module: Install and activate the Upgrade Status module on your Drupal 9 website. Run the scan and analyze the report it generates.

2. Prioritize Code Changes: Focus on addressing critical deprecated code elements that might cause compatibility issues or security vulnerabilities during the migration. You can categorize the findings based on severity and address them accordingly.

3. Manual Code Fixes: For some deprecated code, manual adjustments might be necessary. Utilize the Upgrade Status report to locate the code snippets and consult Drupal documentation or online resources to find the recommended replacements or best practices for addressing the deprecation.

4. Leverage Drupal Rector (Optional): If comfortable with command-line tools, consider using Drupal Rector to automate some of the code fixes. However, always review the changes it makes before deploying them to your live website.

After addressing deprecated code, rigorously test your website’s functionalities within your Drupal 9 development environment. Make sure everything works as expected.

Step 7: Upgrade to Drupal 10

Drupal uses Composer, a dependency management tool, to handle core updates and manage contributed modules and themes. Upgrading the core involves updating the drupal/core package within your composer.json file.

Locate the drupal/core package definition within your composer.json file. Typically, you’ll find it under the require section. Update the version number to the desired Drupal 10 version (e.g., ^10.0).

With the composer.json file updated, execute the following command in your terminal to initiate the upgrade process:

composer update

This command instructs Composer to download and install the necessary Drupal 10 core files and update any dependent packages.

Before executing the actual update, consider using the –dry-run flag with the composer update command.

composer update --dry-run

It helps identify potential conflicts or missing dependencies before proceeding with the actual upgrade.

Post-upgrade Tasks

Step 8: Run Database Updates

After successfully upgrading the Drupal core to version 10, you may need to make some adjustments to the database schema. So it reflects changes introduced in the new version. These adjustments are typically handled through database updates. There are two primary ways to execute these updates:

  • Drupal Interface: Visit the /update.php path in your Drupal 10 administration interface. This page will identify any pending database updates and provide the option to run them with a single click.
  • Drush Commands: Utilize Drush, a powerful command-line tool for Drupal, to execute database updates. The command drush updatedb serves this purpose.

Running these updates ensures your website’s database structure aligns with the latest Drupal 10 requirements. That improves the performance and functionality.

Step 9: Clear Cache

During the migration process, various caches within your Drupal website might store outdated information. Make sure you’re viewing the website with the latest changes implemented in Drupal 10. Clearing the caches would help with that. Here’s how to accomplish this:

  • Drupal Interface: The Drupal administration interface typically offers a built-in cache clearing functionality. The specific location might vary depending on your theme and administration settings. Look for options like “Performance” or “Clear Cache” within the administration menu.
  • Drush Commands: Drush provides a convenient way to clear caches through the command drush cache:clear all. This command removes all cached data within your website, including page cache, block cache, and render cache.

Clearing the cache guarantees that you and your website visitors experience the most up-to-date version of your Drupal website after the upgrade.

Step 10: Test Thoroughly

Upgrading to a new Drupal version can introduce unexpected changes. Rigorous testing is paramount to ensure a smooth user experience and identify any potential issues after the migration. Here are some key areas to focus on during testing:

  • Core functionalities: Test core functionalities like user login, content creation and editing, search functionality, and form submissions.
  • Contributed Modules and Themes: Verify that all your contributed modules and themes function as intended after the upgrade. Look for any visual inconsistencies, layout changes, or broken functionalities.
  • Custom Code: If you have custom modules or themes on your website, meticulously test their behavior in Drupal 10. Ensure they continue to work seamlessly and haven’t introduced any errors or compatibility issues.

By dedicating time to thorough testing, you can catch any potential problems before they affect your website visitors and take corrective actions if necessary.

Step 11: Monitor and Maintain

The migration process marks the beginning of your journey with Drupal 10. Here are some ongoing maintenance practices to keep your website secure, performant, and up-to-date:

  • Security Updates: Drupal releases regular security updates to address vulnerabilities and bugs. Make it a priority to apply these updates promptly to maintain a secure website environment.
  • Module and Theme Updates: Similar to core updates, contributed modules and themes also receive updates with bug fixes, new features, and security enhancements. Regularly update your modules and themes to benefit from these improvements and ensure compatibility with Drupal 10.
  • Regular Backups: Performing regular backups of your website, including both database and files, is crucial for disaster recovery. In case of unforeseen issues, backups allow you to restore your website to a previous working state.

By adhering to these post-upgrade tasks, you can ensure a successful transition to Drupal 10 and lay the foundation for a secure, performant, and future-proof website.

Remember, migrating can be complex, especially for larger websites. Consider seeking help from qualified Drupal developers if you lack the technical expertise or require assistance with the process.

Want us to assist you with Drupal migration?

Challenges with Drupal 9 to Drupal 10 Migration

Although migrating from Drupal 9 to Drupal 10 is quite beneficial, you need to consider some challenges that come with it. Let’s discuss a few:

Compatibility Issues

The biggest challenge often lies in ensuring compatibility with contributed modules and themes. Modules and themes designed specifically for Drupal 9 might not function flawlessly in Drupal 10. You’ll need to verify compatibility, update modules and themes to their latest versions whenever possible, or potentially find alternative solutions.

Deprecated Code

Drupal 9 removes functionalities considered outdated or replaced with better alternatives. Your custom code might contain snippets of deprecated code that need to be addressed before or during the migration. This can involve manual adjustments or leveraging tools like Drupal Rector to automate the process.

Upgrading Dependencies

Drupal 10 relies on updated versions of core libraries and dependencies compared to Drupal 9. Your website hosting environment might require adjustments to meet the new system requirements, such as upgrading the PHP version or ensuring compatibility with specific libraries.


Testing all functionalities, modules, and themes after the migration is crucial to identify any potential issues introduced during the process. This can be a time-consuming task, especially for larger websites with numerous custom components.

Data Migration Issues

While the core migration process focuses on code and configuration, there might be situations where you need to migrate specific data elements. Depending on the complexity of your data, this can require additional scripting or custom development work.

To mitigate these challenges, plan thoroughly with a comprehensive checklist. Identify the potential compatibility issues and have a rollback plan in place in case of unforeseen complications.

If you lack the technical expertise or have a complex website, consider seeking assistance from a professional Drupal development company. Their experience can significantly reduce the time and resources required for a successful migration.

FAQs on Migrating from Drupal 9 to Drupal 10

Is it necessary to migrate from Drupal 9 to Drupal 10 immediately?
No, it is not necessary to migrate immediately unless there is a specific feature or improvement in Drupal 10 that your website needs. However, it is important to keep in mind that support for Drupal 9 will end in November 2023, so it is recommended to plan for the migration in the near future.
Will all of my data be transferred during the migration process?
Most of the data from your Drupal 9 site will be transferred during the migration process, including content, configurations, and user accounts. However, some contributed modules may not have a direct migration path and may require additional steps to ensure their data is transferred properly.
Can I migrate directly from Drupal 7 or 8 to Drupal 10?
No, it’s not recommended to directly migrate from Drupal 7 or 8 to Drupal 10. These versions have reached their end of life and are no longer supported. It is recommended to first upgrade to Drupal 9 and then to Drupal 10.

To Conclude

Migrating from Drupal 9 to Drupal 10 involves updating core and contributed modules, checking for compatibility with Drupal 10, and performing a data migration. It is recommended to consult the official Drupal documentation for a detailed guide on the process.

As with any software, Drupal releases updates and new versions to improve functionality, security, and performance. Migrating to Drupal 10 will ensure that your website is running on the latest and most secure version of the platform. For additional support, you can also opt for our Drupal consulting services for seamless transition.

Need assistance with your Drupal project?

Mayur Upadhyay is a tech professional with expertise in Shopify, WordPress, Drupal, Frameworks, jQuery, and more. With a proven track record in web development and eCommerce development.

Leave a comment