--- title: "Top 10 Steps to Upgrade to Drupal 10" date: "2022-12-20T04:29:07+00:00" summary: image: type: "article" url: "/acquia-cloud-platform/help/89141-top-10-steps-upgrade-drupal-10" id: "cf3f04a4-6738-485c-b773-88bc41fb8063" --- Table of contents will be added **Drupal 10 is here!** What are you waiting for? It's time to upgrade! But... before you do, here are my top ten things to do _before_ you pull the trigger. Remember, the Drupal 10 update is easier than ever...assuming you're ready for it. **10\. Run a Deprecation Scan** ------------------------------- Just like the Drupal 8 to 9 upgrade a few years ago, the main difference between Drupal 9.5 and Drupal 10.0 is the removal of all the deprecated code. What does that mean? If you've got any PHP code that relies on a function that no longer exists, your site is going to white screen and throw fatal errors. Fun, right? Thankfully there are a number of tools you can download and run on your site right now that will tell you if you are compatible with Drupal 10 or not. My personal recommendation is the [Upgrade Status](https://www.drupal.org/project/upgrade_status) module. **Warning:** I would not recommend committing any configuration or composer changes that actually leave Upgrade Status in your codebase or enabled at this point. We'll cover this more below in #3. **9\. Remediate Deprecated Custom Code** ---------------------------------------- Once you have your Upgrade Status report, it's time to start refactoring your code. Hopefully you don't have too much to change, but the bottom line is you cannot do any sort of dry run or actual upgrade to Drupal 10 until you've remediated _all_ of your custom code. Many of the deprecation changes end up being quite minor (replacing one function / method with another). However, don't take these for granted. Even one word replacements can break a website if not handled and tested properly! Most Drupal API changes have automated coverage in drupal-rector, Upgrade Status will tell you when to use that to speed up your work. **8\. Update to PHP 8.1** ------------------------- What about remediating the contributed updates?! Hold on hold on, we'll do that in a moment. But if we're going to run a bunch of module updates, let's _also_ do the PHP 8.1 update. Some modules may also be incompatible with PHP 8.1 so we'll want to try and knock this out at the same time. Remember, all environments must eventually be updated to PHP 8.1 for Drupal 10. For this exercise we'll start with your local environment / Cloud IDE. But as we progress, you'll also need to update any CI/CD environments, your teams' locals, and all cloud environments. Did you know you can add PHP as a dependency in composer as well? It's quite simple and will also help weed out incompatible dependencies. `"require": {` `"php": ">=8.1"` `}` Once in composer, you can `composer update php --with-all-dependences` just like anything else. [I wrote a post recently for updating to PHP 8.1, you can check that out here on the dev.acquia.com blog!](https://dev.acquia.com/tutorial/updating-your-code-studio-project-php-81) **7\. Remediate Deprecated Contrib** ------------------------------------ _Now_ let's update all of those contrib modules to be both D10 and PHP 8.1 compatible. This is best accomplished with composer. Upgrade Status will help you understand which modules have compatible versions and which don't. Thankfully, many many more modules are D10 compatible right now than were D9 compatible at the same point in the release cycle. ![Dashboard showing Drupal 10 project deprecation status with two pie charts detailing project stages and error occurrences. Filters available for customization.](https://acquia.widen.net/content/8354ed79-1faa-46fe-aa7f-d27e6adae00f/web/url_ace06ae5335acf1c1b6c1e683eebdc6b.png) Acquia provides some fairly in depth reporting on the readiness of the community here on dev.acquia.com, you can check that out [here](https://dev.acquia.com/drupal10/deprecation_status/projects). Keep in mind that there may still be modules that are not D10 compatible today. This could block you from updating unless you can help get those projects ready (or you remove them from your project). If you need a contributed project that is not yet ready, Upgrade Status will help find the existing issue or issues where discussion about required fixes is happening. You can `composer require` an incompatible project with [mglaman/composer-drupal-lenient](https://github.com/mglaman/composer-drupal-lenient) and apply needed patches with [cweagans/composer-patches](https://github.com/cweagans/composer-patches). Make sure to provide feedback to project maintainers about patches in the issues. **6\. Update your Other Tools / Plugins** ----------------------------------------- Let's be honest, this "probably" already happened when you updated to PHP 8.1 but it's worth calling out separately. If you're using other tools (e.g. Acquia BLT) that are composer required into your project, you need to make sure that all of these are _also_ compatible with PHP 8.1 and/or Drupal 10.x. Otherwise, these tools will block you from doing the update. **5\. Upgrade to Drush 11 / Install Drush** ------------------------------------------- It's a little confusing, but Drupal 10 will only work with Drush 11. Acquia provides up to Drush 10 on our hosting platform **but we do not provide Drush 11** as Drush 11 must be installed via composer in your codebase. So, if you're already using Drush in your project via composer, all you have to do is upgrade to Drush 11 with `drush/drush: ^11`. However, if you aren't, you'll need to add drush 11 with `composer require drush/drush ^11`. Drush 11 requires PHP 8.1 (good thing we already did that) and Symfony 6.x components (which also require PHP 8.1). Previous versions of Symfony (4 and 5) are PHP 7.4 and 8.0 compatible, hence the jump. **4\. Update to the latest Drupal 9.x** --------------------------------------- As of right now, Drupal 9.5.0 is out. You don't technically have to be running the most current 9.5.x to hit Drupal 10, but 9.5.x is the only branch still receiving bugfixes. While 9.4.x can also be used to update, older versions of Drupal 9 do not have a supported upgrade path. **3\. Remove Upgrade Status** ----------------------------- Now this one may be a little counterintuitive, but go with me. Upgrade Status currently works for Drupal 9.x. It does not work with Drupal 10.x yet. So, believe it or not, you now need to remove Upgrade Status from your code before you can continue. This is why I warned you above in #10 not to leave Upgrade Status installed! **2\. Do a Dry Run** -------------------- I usually assume that major upgrades will fail the first time I try them. I am a strict follower of [Murphy's Law](https://en.wikipedia.org/wiki/Murphy%27s_law) (if it can go wrong, it will go wrong) so having a thorough plan for testing in a safe space so that you can constrain any explosions is only going to make your life easier. Ideally, you'll do _several_ dry runs. For me, I do this locally, in CI/CD, and then in my dev environment at minimum before I even think about pushing a major version update into production! Also, during the dry run, this is a good time to find out if there are any additional packages that might be blocking or controlling your update. A few common ones are... * drupal/core * drupal/core-composer-scaffold * drupal/core-dev * drupal/core-recommended If you still can't get a `composer update drupal/core --with-all-dependencies` to resolve into Drupal 10.x, you can always run `composer why-not drupal/core 10.0` to get some insight into what in your composer dependency tree still requires something other than 10.x. **1\. Back EVERYTHING Up** -------------------------- Finally, when you're ready to do the deployment into your production environment, make sure you have a snapshot of your code and database. Assuming you did dry runs in other environments (and they succeeded) then you should be clear to continue with the update. But... if you have backups, you'll thank me the one time you have a problem. **In Conclusion** ----------------- So that's it! A pretty simple list (and if you did the Drupal 8 to 9 update it should look very familiar). Good luck in your updates!