As new versions of Drupal continue to evolve, each upgrade introduces valuable improvements in performance, accessibility, and security. Therefore, understanding how to perform a proper Drupal upgrade will be a critical step, helping you avoid downtime, data loss, outdated security support, or compatibility issues.
In this guide, we'll walk you through the entire process of Drupal upgrade to the latest version, including:
- Upgrade from Drupal 10 to 11
- Upgrade from Drupal 9 to 10
- Upgrade from legacy Drupal version
- Best practices for a smooth updating process
Without further delay, let's get started!
How to Upgrade from Drupal 10 to 11
Since Drupal 11 is the latest core version, a Drupal upgrade from version 10 to 11 helps your site stay aligned with the latest security standards and long-term support roadmap. In the following steps, we’ll walk through the exact requirements and actions needed to complete a smooth Drupal 10 to 11 upgrade.
Step 1. Check for Drupal 11 requirements
Before starting the Drupal upgrade from version 10 to 11, you need to make sure your site and hosting environment meet all the technical requirements for Drupal 11, including:
- Confirm your hosting environment: Make sure your server environment supports Drupal 11, including the correct versions of PHP, Composer, and your database. You can find the full list of prerequisites in the Drupal 11 platform requirements.
- Update your site to Drupal 10.3+: If your site is running on Drupal 10.2.x or earlier, you must first update to Drupal 10.3.0 or later. This is required because older updates and some core modules/themes were removed and replaced with contributed alternatives.
- Manage altered scaffold files: If you’ve modified core scaffold files like .htaccess, make sure you document those changes before upgrading. After the upgrade, review and reapply your customizations where necessary.
- Resolve deprecated core modules and themes: You should either stop using them in Drupal 10 before upgrading or install the contributed versions of those modules before performing the upgrade.
By meeting these requirements in advance, you’ll avoid common blockers and make the Drupal upgrade to 11 more efficient and reliable.
Step 2. Update contributed modules and projects
Next, you need to make sure all contributed modules and projects are compatible with Drupal 11 and still work correctly on Drupal 10.3+. This step reduces dependency conflicts and prevents the upgrade from failing midway.
- Check module compatibility with Upgrade Status: Use the Upgrade Status module to scan your site and identify contributed modules or projects that are not yet compatible with Drupal 11. This report helps you understand which modules need updates, patches, or manual review.
- Update contributed modules using Composer: Update each contributed module to its latest Drupal 11- compatible version. The recommended approach is to use
composer requireinstead ofcomposer update, because this method ignores existing version constraints defined incomposer.jsonand pulls the newest compatible release. - Re-run Upgrade Status after each update: Alternate between updating modules via Composer and re-running the Upgrade Status report. This process helps you confirm that all contributed modules gradually become compatible with Drupal 11.
- Manually review modules flagged as incompatible: If Upgrade Status reports modules that still need maintainer support, manually check their project pages on Drupal.org. In some cases, Drupal 11–compatible releases already exist but are not automatically detected by the report.
- Apply patches when necessary: If no official Drupal 11 release is available, check the module’s issue queue for compatibility patches. Applying a patch can temporarily resolve the issue, although Composer will not automatically recognize locally patched version constraints.
- Coordinate with maintainers if no solution exists: If a module has no compatible release or patch, consider cooperating with the module maintainers or reviewing their Drupal 11 plans. Many key modules publish compatibility roadmaps or guidance in advance.
- Handle modules that are Drupal 11–only: Some modules may already support Drupal 11 but still need to remain compatible with Drupal 10 during the upgrade process. In this case, update your
composer.jsonfile to allow multiple version constraints, which simplifies dependency resolution and avoids conflicts during the Drupal upgrade.
Step 3. Update custom modules and themes
If your site uses custom modules or themes, this step is critical before continuing the Drupal upgrade from 10 to 11. Drupal 11 removes code that was already deprecated in Drupal 10, so any outdated custom code must be updated in advance.
- Identify deprecated code in custom modules and themes: Review your custom codebase to find APIs and functions that were deprecated in Drupal 10 and fully removed in Drupal 11. Leaving this code unchanged can cause fatal errors during the upgrade.
- Use Upgrade Status and Drupal Rector: Run the Upgrade Status module to scan your custom modules and themes for Drupal 11 compatibility issues. Then, use Drupal Rector to automatically refactor deprecated code where possible, which helps speed up the remediation process.
- Uninstall Upgrade Status (optional): Once Upgrade Status confirms compatibility, you may uninstall and remove the module from your project. This step is optional, as Upgrade Status is now compatible with Drupal 11.
- Consider Drush removal before upgrade (optional): Some teams choose to temporarily remove Drush before upgrading core to avoid potential conflicts. If you follow this approach, remember that you will need alternative methods to perform tasks normally handled by Drush until it is reinstalled after the upgrade.
Step 4. Run the Drupal upgrade from 10 to 11
Once your environment, contributed modules, and custom code are ready, you can proceed with the Drupal upgrade to version 11. You should run all commands from your Drupal project root, where the composer.json file is located.
- Temporarily grant write access to protected files and directories using the following command line. This step allows Composer and Drupal to update scaffold files during the upgrade.
chmod 777 web/sites/default
chmod 666 web/sites/default/*settings.php
chmod 666 web/sites/default/*services.yml
- Update Drupal core packages to Drupal 11 (without installing yet) to avoid dependency conflicts during version resolution.
composer require 'drupal/core-recommended:^11' \
'drupal/core-composer-scaffold:^11' \
'drupal/core-project-message:^11' --no-update
- Remove a separate drupal/core requirement if it exists:
composer remove drupal/core --no-update
- Update drupal/core-dev if it is installed:
composer require 'drupal/core-dev:^11' --dev --no-update
- Update Drush to a Drupal 11–compatible version (if installed):
composer require 'drush/drush:^13' --no-update
- Test the update process with a dry run:
composer update --dry-run
- Perform the actual update once the dry run completes without errors:
composer update
- Verify the installation process to ensure that other developers or deployment pipelines will not face issues. If everything is correct, Composer will report no errors and display the message “Nothing to install, update or remove.”
composer install
- Run database updates after updating the codebase:
drush updatedb:status
drush updatedb
If errors occur, resolve them and rerun drush updatedb until all updates are completed successfully.
- Restore read-only permissions once the Drupal upgrade finishes:
chmod 755 web/sites/default
chmod 644 web/sites/default/*settings.php
chmod 644 web/sites/default/*services.yml
Step 5. Run post Drupal upgrade tasks
1. Export and review configuration
After completing the Drupal upgrade, you should export and commit your configuration if you use configuration management. Core updates can reorder YAML files or override settings during database updates. Before committing changes, run a git diff to confirm that no critical functionality is affected.
2. Run PHPCS to align coding standards
If your project uses PHPCS, you should run it after the upgrade because Drupal coding standards may have changed. Apply automated fixes where possible and review remaining warnings manually to keep your codebase consistent.
3. Run automated tests
If your site includes custom tests such as PHPUnit or Behat, you should run them to confirm that core functionality still works as expected. This step helps detect hidden issues early.
4. Manually test site functionality
You should manually test key pages, forms, and user flows in the browser. While testing, monitor the Drupal watchdog log to catch errors or warnings in real time: drush watchdog:tail
5. Check for errors via database updates and cron
Some issues only appear when database updates or background tasks run. You should execute pending database updates and cron jobs to surface these problems: drush updatedb -y
Step 6. Resolve common issues
During a Drupal upgrade from 10 to 11, Composer-related errors are common, especially on complex projects with many dependencies. The table below summarizes the most frequent issues and how to resolve them effectively.
Problem | Cause | Solution |
Your requirements could not be resolved to an installable set of packages | One or more dependencies are not compatible with Drupal 11, or existing version constraints in composer.json block the upgrade. | Re-require all direct dependencies to reset version constraints: composer show --no-dev --direct --name-only | xargs composer require --no-updateThen run a dry update again. |
Some dependencies only support Drupal 11 via RC or alpha releases. | Identify those dependencies and explicitly allow RC or alpha versions (for example, @RC or @alpha). Then re-run Composer with dependencies: composer require --update-with-dependencies | |
A specific module version blocks the upgrade. | Check the module’s project page on Drupal.org and explicitly require a Drupal 11–compatible version: Composer require drupal/MODULE_NAME:^2.0.0-rc1 --no-update | |
You need to identify what blocks Drupal 11 core. | Run the following command to see all blocking dependencies: composer why-not drupal/core ^11 | |
Composer patches do not reapply | Existing patches no longer apply to Drupal 11 or have already been committed upstream. | Remove obsolete patches from composer.json. If a newer patch exists for Drupal 11, replace the patch link in composer.json and rerun the update. |
Lock file is not up to date with the latest changes | The composer.lock file does not match the current composer.json. | Delete the lock file and vendor directory, then rerun Composer: rm composer.lock |
How to Upgrade from Drupal 9 to 10
Since Drupal 9 reached its end-of-life in November 2023, it's important to update your site to version 10 to stay supported. In the following sections, we’ll guide you through each step of the Drupal upgrade from 9 to 10 process so you can complete the transition confidently and without disruption.
Step 1. Check Drupal 10 requirements
Before starting the Drupal upgrade from 9 to 10, you need to confirm that your site and server environment meet all Drupal 10 requirements. Preparing these elements early helps avoid upgrade blockers and unexpected errors.
- Confirm the hosting environment: Your hosting environment must meet the Drupal 10 platform requirements, including supported PHP, database, and server configurations.
- Update your site to Drupal 9.4 or 9.5: Your website must run on Drupal 9.4.x or 9.5.x before upgrading to Drupal 10. Earlier Drupal 9 versions are not supported for a direct upgrade.
- Review removed modules and themes: Some modules and themes may have been removed in Drupal 9 minor releases. If this happens, you should replace them with the appropriate contributed projects before continuing.
- Manage altered scaffold files: Core files such as
.htaccesswill change during the Drupal 9 to 10 upgrade. If you modified any scaffold files, you should document those changes and reapply them after upgrading. Drupal 10 introduces important CSS, JavaScript aggregation improvements, and updated.htaccessrules. - Resolve deprecated core modules and themes: Several Drupal core modules and themes deprecated in Drupal 9 are removed in Drupal 10. This includes the Seven admin theme and CKEditor 4. You should either stop using deprecated extensions in Drupal 9 or install the contributed versions of these extensions before running database updates.
Step 2. Update contributed modules and projects
To ensure a smooth Drupal upgrade from 9 to 10, all contributed modules and projects must be compatible with Drupal 10 while still functioning on your Drupal 9.4+ site.
- Check compatibility using Upgrade Status: Use the Upgrade Status
module to scan your contributed modules. Alternate between running the scan and updating modules until all projects are listed as Drupal 10 compatible. - Update modules using Composer: Use composer require instead of composer update to bypass version constraints and install the latest compatible version:
composer require drupal/webform:^6.2 --no-update
- Handle Drupal 10–only modules: Some modules are only compatible with Drupal 10. In this case, modify your
composer.jsonfile to allow compatibility with both versions using Composer’s logical OR operator. For example:
"drupal/remove_http_headers": "^1.0 || ^2.0"
- Remove incompatible tools (Drupal Console) as it's not Drupal 10 compatible:
composer remove drupal/console --no-update
- Uninstall Upgrade Status after validation (optional):
drush pm:uninstall upgrade_status -y
composer remove drupal/upgrade_status --no-update
- Remove Drush before upgrade (optional): You can remove Drush temporarily before the upgrade to avoid version conflicts between Drush and core packages.
Step 3. Update custom modules and themes
Before running the Drupal upgrade from 9 to 10, you must update all custom modules and themes to remove deprecated code that is no longer supported in Drupal 10. This step is essential to avoid fatal errors during the core Drupal upgrade.
- Check custom code compatibility with Upgrade Status: On the report page, run a scan under the “Fix manually” section to identify deprecated APIs and suggested replacements.
- Automatically replace deprecated code with Drupal Rector: After installing Drupal Rector according to its GitHub documentation, preview the proposed changes by running it in dry-run mode:
vendor/bin/rector process docroot/modules/custom --dry-run
- If the preview looks correct, apply the changes by running the same command without the –dry-run flag:
vendor/bin/rector process docroot/modules/custom
- Rerun Upgrade Status and apply manual fixes: After running Drupal Rector, rerun the Upgrade Status report to verify progress. Although the number of issues should be reduced, some deprecated code may still require manual updates.
- Uninstall Upgrade Status and Drupal Rector when complete:
drush pm:uninstall upgrade_status -y
rm rector.php
composer remove palantirnet/drupal-rector drupal/upgrade_status --no-update
Step 4. Perform the Drupal upgrade from 9 to 10
After preparing your environment, contributed modules, and custom code, you can proceed with the Drupal upgrade from 9 to 10. You should run all commands from your Drupal project root, where the composer.json file is located.
- Temporarily grant write access to protected files and directories:
chmod 777 web/sites/default
chmod 666 web/sites/default/*settings.php
chmod 666 web/sites/default/*services.yml
- Update Drupal core packages to Drupal 10 (without installing yet):
composer require 'drupal/core-recommended:^10' \
'drupal/core-composer-scaffold:^10' \
'drupal/core-project-message:^10' --no-update
- Remove a separate drupal/core requirement if it exists:
composer remove drupal/core --no-update
- Update drupal/core-dev if it is installed:
composer require 'drupal/core-dev:^10' --dev --no-update
- Update Drush to a Drupal 10–compatible version (if installed):
composer require 'drush/drush:^12' --no-update
- Test the update process using a dry run:
composer update --dry-run
- Perform the actual update once the dry run completes:
composer update
- Verify the installation process to ensure other developers and deployment pipelines can install dependencies without errors:
composer install
- Run database updates:
drush updatedb
- Restore read-only permissions when the Drupal upgrade is complete:
chmod 755 web/sites/default
chmod 644 web/sites/default/*settings.php
chmod 644 web/sites/default/*services.yml
Step 5. Run post Drupal upgrade tasks
1. Export and review configuration
After completing the Drupal upgrade, you should export and commit your configuration if you use configuration management. Core updates can reorder YAML files or override settings during database updates. Before committing changes, run a git diff to confirm that no critical functionality is affected.
2. Run PHPCS to align coding standards
If your project uses PHPCS, you should run it after the upgrade because Drupal coding standards may have changed. Apply automated fixes where possible and review remaining warnings manually to keep your codebase consistent.
3. Run automated tests
If your site includes custom tests such as PHPUnit or Behat, you should run them to confirm that core functionality still works as expected. This step helps detect hidden issues early.
4. Manually test site functionality
You should manually test key pages, forms, and user flows in the browser. While testing, monitor the Drupal watchdog log to catch errors or warnings in real time: drush watchdog:tail
5. Check for errors via database updates and cron
Some issues only appear when database updates or background tasks run. You should execute pending database updates and cron jobs to surface these problems: drush updatedb -y
Step 6. Resolve common issues
During the Drupal upgrade from 9 to 10, Composer errors are the most common blockers. The table below summarizes typical issues you may encounter and the recommended ways to resolve them.
Problem | Cause | Solution |
“Your requirements could not be resolved to an installable set of packages” | One or more dependencies are not compatible with Drupal 10, or existing version constraints in composer.json block the upgrade. | Reset version constraints for all direct dependencies: composer show --no-dev --direct --name-only | xargs composer require --no-update |
Some dependencies only support Drupal 10 via RC or alpha releases. | Identify affected dependencies and explicitly allow RC or alpha versions (for example, @RC or @alpha). Then re-require all dependencies with updates: composer require --update-with-dependencies | |
A specific Drupal module blocks the upgrade. | Check the module’s Drupal.org page and explicitly require a Drupal 10–compatible version: composer require drupal/MODULE_NAME:^2.0.0-rc1 --no-update | |
You need to identify which dependencies block Drupal 10 core. | Run the following command to list blocking dependencies: composer why-not drupal/core ^10 | |
Composer patches do not reapply | Existing patches no longer apply to Drupal 10 or have already been committed upstream. | Remove obsolete patches from composer.json. If a newer patch exists for Drupal 10, update the patch URL in composer.json and rerun the update. |
Lock file is not up to date with the latest changes | The composer.lock file does not match the current composer.json. | Delete the lock file and vendor directory, then rerun Composer: rm composer.lock |
How to Upgrade from Legacy Drupal Versions
If your website is still running on Drupal 6, 7, 8, or even 9, it’s important to know that all of these versions have reached end-of-life (EOL). This means they no longer receive official support, security updates, or bug fixes from the Drupal community. Running a site on an outdated version exposes you to a wide range of risks and limitations, including:
- Security vulnerabilities: Without patches, your site becomes an easy target for exploits and data breaches.
- Incompatible infrastructure: Older versions don’t support modern PHP versions or database systems, making hosting and performance unstable.
- Limited module support: Most contributed modules and themes no longer provide updates for legacy versions.
- Missing features and improvements: You miss out on performance upgrades, accessibility enhancements, and editor tools like CKEditor 5.
If you're ready to stay within the Drupal ecosystem, the best path is to upgrade Drupal 6 to 7, upgrade Drupal 7 to 8, upgrade Drupal 8 to 9, then run the Drupal upgrade to the latest version (10 and 11). This will give your site continued access to security updates, modern development practices, and all the latest features.
If you're unable to upgrade immediately, you can purchase extended security support through trusted providers. For example, the Drupal Steward Program offers paid protection against critical vulnerabilities for Drupal 7, giving site owners more time to plan their upgrade without leaving their site exposed.
Alternatively, you may consider this a good time to migrate to another platform, especially if you're looking for something more user-friendly, cost-effective, or aligned with your current business goals.
If you choose to go this route, LitExtension can help you make a smooth transition. As the #1 eCommerce Migration Expert, LitExtension supports secure, accurate, and automated migrations from Drupal to platforms like Shopify, WooCommerce, Magento, and more, with minimal disruption and full data integrity.
Let Our Experts Handle Your Store Migration!
With the All-in-One Migration Service, our experts take care of everything, ensuring a seamless and stress-free migration.
Best Practices for a Smooth Drupal Upgrade
A successful Drupal upgrade depends on careful planning, thorough testing, and a clear execution process. Here are the best practices you can follow to ensure a seamless upgrade.
- Prepare backups and a staging environment: Before starting, you should create full Drupal backups of your database and files. A staging environment lets you test the upgrade safely and catch issues before they reach your live site.
- Check compatibility early: You should review contributed modules, themes, and custom code before upgrading Drupal core. Tools like Upgrade Status help you identify deprecated code and unsupported extensions early in the process.
- Use Composer consistently: You should rely on Composer for managing Drupal core, modules, and dependencies. Running dry runs and resolving conflicts early helps prevent failed upgrades.
- Test thoroughly after the upgrade: After the upgrade, you should test key site features such as forms, content, and integrations. Reviewing logs and applying database updates ensures your site remains stable and secure.
- Plan for ongoing maintenance: Once the upgrade is complete, you should keep Drupal core and modules updated regularly. This habit helps you avoid large, risky upgrades in the future and keeps your site secure.
Drupal Upgrade – FAQs
Can I upgrade from Drupal 9 to 11?
You cannot upgrade directly from Drupal 9 to Drupal 11. Drupal follows a sequential upgrade path, so you must first upgrade from Drupal 9 to Drupal 10, then continue from Drupal 10 to Drupal 11. This approach ensures compatibility with core changes, dependencies, and deprecated APIs at each stage.
What is the latest Drupal version?
The latest major version of Drupal is Drupal 11. It offers long-term security support, improved performance, and better alignment with modern PHP and Symfony versions. Using the latest Drupal version helps keep your site secure and compatible with current technologies.
What are the approaches to a Drupal upgrade?
There are two main approaches to a Drupal upgrade. The first is an in-place upgrade, which works for supported version paths such as Drupal 9 to 10 or 10 to 11 and focuses on updating core, modules, and code. The second approach is a migration, which is required for legacy versions like Drupal 6, 7, or 8 and involves rebuilding the site on a newer Drupal version or moving to another platform while transferring content and data.
Final Words
To conclude, a Drupal upgrade is an essential step to keep your website secure, stable, and ready for future growth. Whether you are upgrading between supported versions or moving away from a legacy Drupal setup, proper planning and careful execution make a significant difference. By following the recommended upgrade path, preparing your codebase, and completing post-upgrade checks, you can reduce risks and avoid unexpected downtime.
If you like articles like this, don't hesitate to check out our LitExtension Resources and Blogs for more expert tips and insights.
