Using composer to upgrade to Drupal 9

Before updating

Follow the directives on the Upgrading to Drupal 9 page:

Drupal 9 requires a settings.php change.

As with any major update, make a full backup (filesystem and database) before you begin.

Institute Communications update process

Institute Communications has provided an update script to assist with this upgrade. Refer to Institute Communications' gt_installer Drupal 8 to Drupal 9 update process to update GT Theme, GT Tools, and GT Profile to their latest versions.

Upgrade Process

1. Install Upgrade Status and read the report

Install Upgrade Status like you would any other module:

composer require drupal/upgrade_status
drush en upgrade_status
drush cr

After enabling the module and clearing caches, navigate to Reports > Upgrade Status (admin/reports/upgrade-status). On the Upgrade Status page, make a note of the Remove and Update sections.

Remove shows uninstalled modules and themes that are not compatible. You can remove each project using:

composer remove drupal/PROJECTNAME

Update shows each project which needs a Drupal 9-compatible release. For each project, go to the Issues (or the associated Drupal.org module page) and make a note of what version is required for Drupal 9 compatibility.

2. Upgrade Drupal modules/themes to 9.x-compatible releases

Using the knowledge from Upgrade Status' Update list above, upgrade each module to its recommended Drupal 8 and Drupal 9 release:

composer require drupal/imageapi_optimize:^4.0

If you are unsure of how to write the composer require statement, each project release (e.g. drupal/imageapi_optimize:^4.0) has an Install with Composer text snippet to copy and paste.

Repeat this for each project that needs a new version for Drupal 9 support. Then, upgrade the database on your Drupal website by going to {website}/update.php.

Note for Drupal 9-only releases

Most modules, including all dependencies of the Drupal 8 Drupal Express install, have releases that are compatible with both Drupal 8 and Drupal 9:

Drupal.org module project download pages (e.g. faqfield:7.0) show compatibility with both versions with
```
Requires Drupal: ^8 || ^9
```

However, there are release that require just Drupal 9. For those modules (such as permissions_by_term:3.0), you will need to upgrade them while upgrading to Drupal 9.x.

3. Upgrade Drupal core to 9.x

From the drupal.org docs:

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

Please note the argument --no-update, which:

We use --no-update to avoid a chicken-and-egg problem with mutual dependencies.

--no-update

4. Commence upgrade!

Think you've updated all your modules and themes, and can begin the Drupal Core update to Drupal 9? Begin the update:

composer update

Make a note of any composer error message during this process.

5. Update Drupal

Now, run the database updates.

If things broke

If composer goes haywire and you find yourself in purgatory, replace the composer.json with your pre-upgrade backup version, and delete the composer.lock file. Then, force composer to recheck and reinstall modules back to their old versions with:

composer install

Printer-friendly version