Acquia Developer Portal Logo

Drupal 11 Preparation Checklist

Drupal 11 is early! But don’t panic, the new Drupal 10 support model means you are not under pressure to upgrade. Drupal 10 will continue to be supported until mid-late 2026. But as we know, it’s best to be prepared and understand the upgrade process when that time comes for your organization.

Similar to the upgrade from Drupal 9 to Drupal 10, the latest version of Drupal 10 - Drupal 10.3.1 - defined all the deprecated code for Drupal 11. Also like previous modern Drupal major version upgrades there is a recommended set of areas to focus in order to get your applications upgraded as cleanly as possible.

5 steps

These important considerations are: ensuring your environment is ready for Drupal 11, ensuring your Drupal site is updated to the latest version of Drupal 10, updating the contributed modules to the latest versions, updating your custom module code, and then finally update to the next major version of Drupal core itself.

5 steps

The following is a checklist of considerations to help site owners get ready for their Drupal 11 upgrade. These are not documented in a particular order and your organization may have preferences in exactly the order of steps you take to upgrade.

Platform Requirements

To run Drupal 11 in your environment you will need to check with the requirements listed below. On Acquia Cloud, the only changes you will need to make are to update to PHP 8.3 and use the MySQL 5.7 Backport module.

Update to PHP 8.3

Drupal 11 requires PHP 8.3 with the zlib extension enabled. Most systems will already have this extension enabled by default. In the development or sandbox environment where you plan to do the initial upgrade, you should have PHP 8.3 enabled. This is a good thing, because PHP 8.3 is much faster than earlier versions of PHP.

PHP 8.3 is faster

Update to Drush 13

If you use Drush, make sure you update to Drush 13. In the development or sandbox environment where you plan to do the initial upgrade, you should have Drush 13 available.

As needed you can do this with: composer require drush/drush ^13

Database

The requirements for the database drivers supported by Drupal 11 are as follows:

  • The MySQL database driver requires MySQL 8.0. Drupal 11 does not directly use MySQL 8 specific syntax yet, but it will in future versions. If you can't yet upgrade to MySQL 8.0, there is the MySQL 5.7 backport module that you can use temporarily.
  • On Acquia Cloud, customers will need to use the MySQL 5.7 Backport module for now.
  • The MariaDB database driver requires MariaDB 10.6. Drupal 11 does not directly use MariaDB 10.5 specific syntax yet, but it will in future versions. If you can't yet upgrade to MariaDB 10.6, there is the MariaDB 10.3 backport module that you can use temporarily.
  • The PostgreSQL database driver requires PostgreSQL 16.
  • The SQLite database driver requires SQLite 3.45 with the json1 extension.

Web Server

Apache is the most commonly used web server for Drupal. Drupal requires Apache 2.4.7 or greater. Drupal 11 does not provide a web.config file. Support for IIS is removed so sites using IIS are encouraged to change to a supported web server. If you encounter bugs, you are encouraged to report them in case they affect web servers other than IIS.

Dependencies

  • Symfony 7
  • jQuery 4
  • PHPUnit 10
  • Composer 2.7.7

More information about platform requirements is available on drupal.org. 

Upgrade to the Latest Drupal 10

Upgrade to Drupal 10.3 if you have not already. Drupal sites running 10.2.x or earlier versions must first update to 10.3.0 or later because all core updates added prior to 10.3.0 have been removed. In general, sites should update to the most recent release of their current major branch before updating to the next major release.

Run a Deprecation Scan

Like previous modern Drupal major version upgrades, the main difference between Drupal 10.3 and Drupal 11.0 is the removal of all the deprecated code. What that means is that if you have functionality in your site that relies on removed PHP code, you’ll run into errors. So we want to avoid that up front. There are a number of tools you can use on your site that will tell you if you are compatible with Drupal 11 or not.

One highly recommended solution here is the Upgrade Status module. 

Upgrade Status

Analyze with Upgrade Status

Install Upgrade Status on your development site as you would any other Drupal module. Upgrade Status helps “gamify” the process to a certain degree, giving you a checklist of the next steps you might need to perform. 

Use the Administer >> Reports >> Upgrade Status page to check if there are contributed modules you can update to get compatible. The module will also help you learn about the deprecated API uses you can fix in your custom code. Use the latest Drupal 10.3 release to check to make sure all deprecated APIs are detectable.

Leverage Drupal Rector

Drupal Rector is available as well to help automatically fix code issues. You should use drupal-rector to review and update any issues in your custom code. Upgrade Status will help you identify where to take what actions, as warranted. Drupal Rector will also take the steps of leaving “To Do” comments in your code to direct humans on what needs to be done. Learn more about Drupal Rector today.

Check Project Update Bot

Right now contributed projects on drupal.org are receiving help from the Project Update Bot to be Drupal 11 ready. The bot runs on every project on drupal.org and opens issues with compatibility that need to be addressed. Learn about the Project Update bot on Drupal.org.

Remediate Deprecated Contributed Code

Now let's update all of those contrib modules to be Drupal 11 compatible. This is best accomplished with Composer. As mentioned, Upgrade Status will help you understand which modules have compatible versions and which don't. Thankfully, many modules are D11 compatible right now.

Additionally, Acquia provides some fairly in depth reporting on the readiness of community modules here on dev.acquia.com on the Drupal 11 project deprecation status dashboard. Try it out today!

Dashboard

Keep in mind that there may still be modules that are not D11 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 and/or apply needed patches with cweagans/composer-patches. Make sure to provide feedback to project maintainers about patches in the issues.

Remediate Deprecated Custom Code

Much like correcting any contributed code, after receiving your Upgrade Status report, you will need to check your custom code. You might be fortunate to have only a few modifications to make, but the truth is that any sort of trial run or actual transition to Drupal 11 can't proceed until all Drupal application code has been corrected. 

Often, you'll find that the depreciations necessitate only slight modifications (such as swapping out one function or method for another).

Nonetheless, it's important not to underestimate these adjustments. Substitutions as simple as a single word could potentially disrupt your site if they aren't managed and verified with care.

Upgrade Status

Update Your Other Tools As Needed

If your project is using other tools that are Composer required into your project, you need to make sure that all of these are also compatible with PHP 8.3 and/or Drupal 11.x. Otherwise, these tools will block you from doing the update. An example here is BLT which isn't compatible with Drupal 11 (and is undergoing an EOL). If your project is using BLT, then you will need to remove it from the codebase prior to upgrading to Drupal 11. If your site is hosted on Acquia Cloud and you are using BLT and you plan to remove BLT from your workflow and codebase, there is a great tutorial on removing BLT on dev.acquia.com.

Do A Dry Run

If you've done this type of update in the past you are probably, like me, assuming it will fail at least the first time. That's OK because you should always be doing this type of work and testing in a safe space like a local sandbox or cloud IDE where - if and when things go wrong - nothing important will break. Likely, you'll do several dry runs. 

Research how to utilize: composer update --dry-run

Once you get a dry run result with no errors, you are ready to do the core composer update.

If you still can't get a composer update drupal/core --with-all-dependencies to resolve into Drupal 11.x, you can always run composer why-not drupal/core 11.0 to get some insight into what in your composer dependency tree still requires something other than 11.x.

Always Backup Everything

Finally, when you're ready to do the deployment into your production environment, make sure you have an up-to-date 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, it’s always best to back things up just in case.

Additional Resources

More Like This