Upgrade to Drupal 10 for Drupal 9, 10

Update to Drupal 9.4.4 or later

Before you can upgrade your site to Drupal 10 it needs to be on 9.4.4 or 9.5.x. It's best practice to update to the most recent release of Drupal 9 before upgrading to Drupal 10. But, upgrades from 9.4.4 are supported (in addition to 9.5.x), which is unique to Drupal 9-to-10 upgrades.

If you need to update your Drupal 9 site first learn how to perform a minor version update, then come back to this tutorial.

Update to CKEditor 5

If your site is using CKEditor 4, you will need to first ensure your site is on at least Drupal 9.4.4. (See previous step.) The data upgrade path from CKEditor 4 to 5 is not available before 9.4.4.

• Updating to CKEditor 5 is a manual process, but with upgrade paths.
• Most sites using CKEditor 4 should update to CKEditor 5. See also Recommendations for Deprecated Modules: CKEditor.
• If the site has additional installed Drupal modules that provide CKEditor 4 plugins with no CKEditor 5 equivalent as of yet, then you can install the CKEditor 4 contributed module, as a stop-gap until your CKEditor suite of plugins is CKEditor 5-compatible. See Upgrade coordination for modules providing CKEditor 4 plugins. Note: CKEditor 4 will reach its end-of-life at the end of 2023.

Having considered the above points, here's how to upgrade from CKEditor 4 to CKEditor 5:

1. Upgrade to Drupal 9.4.4 or higher.

2. Create a database snapshot as a precaution.

3. Update modules that provide additional CKEditor 4 plugins to the latest release of the major version you're on. Modules that have added CKEditor 5 support should provide support for both CKEditor 4 and 5, and provide an automated upgrade path for toolbar items and plugin settings from 4 to 5.

4. Enable the CKEditor 5 module.

5. Convert text formats to use CKEditor 5. Text formats must be updated one at a time, but switching the editor to CKEditor 5 will automatically migrate your text format configuration to CKEditor 5.

6. Using the Manage administrative menu, navigate to Configuration > Content authoring > Text formats and editors. In the column labeled Text editor, you can tell which text formats are using CKEditor.

7. For each text format that uses CKEditor, under the Operations column, select Configure.

8. On the configuration page for the text format, under Text editor, select CKEditor 5. Status messages will appear letting you know what changed.

   Image

   

9. Scroll to the end of the configuration page and click Save configuration.

After you have updated all CKEditor text formats to CKEditor 5, on the Text formats administrative page, you should see CKEditor 5 listed next to each text format you updated.

Image

QA your content

Important! After you have manually updated each text format that was using CKEditor to use CKEditor 5, it's a good idea to check a representative sample of content that uses the new CKEditor 5 text format to ensure that all tags and content are intact.

Uninstall CKEditor (deprecated)

After you have ensured your site's text format updates were a success, uninstall the deprecated CKEditor module:

1. Using the Manage administrative menu, navigate to Extend > Uninstall.
2. Select CKEditor (Deprecated).
3. Scroll to the end of the page and click Uninstall.

See also How to upgrade from from CKEditor 4 to CKEditor 5.

Update all your contributed projects

Important note: You should update all your contributed modules and themes to Drupal 10 compatible versions while you're still on Drupal 9.

It's a good idea to update all your contributed modules and themes to their latest versions as well. Before you can upgrade Drupal core to version 10, you'll need to ensure that all of your contributed projects are already Drupal 10 compatible. In most cases this will mean updating to the latest version. In some cases this may require additional work if the module isn't already Drupal 10 ready.

• 13.6 Updating a Module
• 13.7 Updating a Theme

Look at the project's page on Drupal.org for more details about compatibility:

Image

Acquia has created a useful tool for checking compatibility.

These are good for getting an estimate of what's going to be involved for your project.

Tip: Check Extend > Uninstall for any deprecated modules (they will be listed at the top). Only uninstall CKEditor (deprecated) after you have performed the manual process of upgrading your CKEditor-using text formats (see previous step).

Use Upgrade Status module

When you're ready to start working on the Drupal 10 readiness of the modules installed on your site, use the Upgrade Status module on your current site to generate a report. Use the 4.x version for Drupal 9 to 10 upgrades. You will need to install a version of Drupal's developer dependencies (drupal/core-dev) that matches your current Drupal 9 site's version. Note: With some older versions of drupal/core-dev, you will first need to composer remove drush/drush (if you have Drush already installed).

Here's an example of installing Upgrade Status on a Drupal 9.4.9 site that has Drush installed. See the Upgrade Status for more information on the current 4.x release and how to install it.

composer show drupal/core | grep versions
# versions : * 9.4.9
composer remove drush/drush
composer require --dev drupal/core-dev:9.4.9 --update-with-all-dependencies
composer require 'drupal/upgrade_status:^4.0@alpha' # See project page for current version in 4.x branch
composer require drush/drush
drush en upgrade_status

Note: Replace 9.4.9 with your site's Drupal 9 version from the composer show drupal/core | grep versions output.

Then, using the Manage administrative menu, navigate to Reports > Upgrade status to see the report and take action.

Image

If a module isn't Drupal 10 compatible you've got a few options:

• Update it yourself. This similar to updating custom code. (See below.)
• Wait for a future release of an updated Drupal 10-compatible version.
• Hire someone to do the updates for you.

We recommend starting with your custom code. And once that's done, come back to your contributed modules and figure out which ones are the most critical for your project and see what you can do to help update them for Drupal 10. In many cases there's likely a patch already available and waiting for community members to test it out.

Update your custom code

If your project has custom modules or themes, it's your responsibility to ensure that that code is compatible with Drupal 10. Using an IDE with support for the @deprecated annotation can help you identify deprecated code. Drupal core deprecations (and new features) will have change records in Change records for Drupal core.

You can use Upgrade Status to scan these projects as well. And then you'll need to remove all use of deprecated APIs. Learn more about what deprecated code is and how to deal with it.

Tip: Even if you're not planning to upgrade to Drupal 10 now you should start doing this. It'll save time in the future, and since Drupal 10 is backward-compatible with Drupal 9.5.x it shouldn't affect your existing site.

Verify your hosting meets the new requirements

The system requirements for Drupal have changed. You'll want to make sure your web server, PHP, and MySQL/MariaDB are all running compatible versions. Upgrade Status will indicate if the Environment is incompatible on its report as well. (This is only useful if the environment on which you're running Upgrade Status is the same as the environment in which you'll be hosting your Drupal 10 site.)

Check the Upgrade Status report

Using the Manage administrative menu, navigate to Reports > Upgrade status and, if necessary, click the Check available updates link under the Gather data column.

Once you have addressed all of the blockers to a Drupal 10 upgrade, you will see "N/A" in the Fix incompatibilites column and "100%" in the Relax column (along with other information).

Image

Update drupal/core-dev (if applicable)

If you have the drupal/core-dev dependencies installed you'll need to update those with:

composer require drupal/core-dev:^10.0 --dev --no-update --update-with-dependencies

Update drupal/core-* projects

Then update the drupal/core-recommended, drupal/core-composer-scaffold, and drupal/core-project-message projects:

composer require drupal/core-recommended:^10.0 drupal/core-composer-scaffold:^10.0 drupal/core-project-message:^10.0 --no-update --update-with-all-dependencies

Run composer update

Then tell Composer to try and resolve and download all the new code:

composer update

If this is successful you'll see line like the following the output:

  - Upgrading drupal/core-dev (9.4.9 => 10.0.4)

If you get any errors you'll need to troubleshoot what's causing the issue. We've tried to provide guidance on some common ones below.

Deploy your code and put site in maintenance mode

Deploy your code and put your site in maintenance mode in order to run database updates.

Important: Remember to make a backup first. These next few steps will change your database schema and are not reversible.

drush state:set system.maintenance_mode 1
drush cache:rebuild

Or, using the administrative UI:

• Maintenance mode: Configuration > Development > Maintenance mode (admin/config/development/maintenance)
• Clear caches: Configuration > Performance (admin/config/development/performance)

Check for and run database updates

If Composer was successful at upgrading your site's dependencies to Drupal 10, then check for database updates.

Using Drush:

drush updatedb

Or navigate to /update.php and navigate through the Drupal database update wizard.

Take your site out of maintenance mode

After database updates have successfully run, take your site out of maintenance mode and rebuild caches.

drush state:set system.maintenance_mode 0
drush cache:rebuild

Celebrate! You've upgraded to Drupal 10!

Congratulations! You've upgraded your site to Drupal 10!

Image