How to upgrade from Drupal 8 to Drupal 9

How to upgrade from Drupal 8 to Drupal 9

This page provides instructions on how to upgrade from Drupal 8 to Drupal 9. For upgrading from prior versions of Drupal (such as Drupal 6 and 7), see Upgrading from Drupal 6 or 7 to Drupal 8. 

There are separate instructions for minor and patch version site updates. (For example, updating from Drupal 9.3.6 to 9.3.8, or 9.2.14 to 9.3.8.)

Prerequisites

  • Your site must be updated to the latest minor version. Upgrades are only supported from the final scheduled minor release and one previous (e.g. Drupal 8.8 and 8.9), not from earlier releases (e.g. Drupal 8.3). Follow the update instructions.
  • You should upgrade any outdated modules on your site to their latest versions. Older module versions may not be compatible with Drupal 9.
  • Your hosting environment must meet the minimum system requirements for the Drupal version you are upgrading to (e.g. PHP 7.4 or later).
  • Check if you have deprecated code in your site that was removed in the next major version. Fix any deprecations, if required. The Upgrade Status module can help you with this. You might have to upgrade several modules.

The actual upgrade process will depend on whether your current site was built using Composer or tarballs (tar.gz files).

If going the Composer route, these instructions are for sites based on drupal/recommended-project or drupal/legacy-project, or derivatives, and not drupal-composer/drupal-project-based sites. See Update Drupal from Versions Prior to 8.8.x using Composer for instructions on converting to the newer 8.8+ compatible model.

Upgrading a Composer-based Drupal 8 site

Perform the following steps from your Drupal 8 site's root (where composer.json lives).

  1. Temporarily add 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

  2. Next, you'll need to pull in both the Drupal 9 version of core-recommended and dev-dependencies packages as dependencies. We use --no-update to avoid a chicken-and-egg problem with mutual dependencies:
     

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

    If you have drupal/core-dev installed:

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

  3. Now, actually perform the update to the code itself:
     

    composer update

    Note: If any of your packages doesn't have a release explicitly declared as D9-compatible, you will likely run into a dependency error when trying to update your codebase. There may already be a patch in the issue queue that you can use if you use to 'upgrade' the project to be drupal 9 compatible. Please refer to this documentation for more details on how to handle this situation: https://www.drupal.org/docs/develop/using-composer/using-drupals-lenient...

    Another, less recommended way to get around this, is you can add an alias to drupal/core, such as:

    composer require "drupal/core:9.0.0 as 8.9.0" --no-update && composer update

    (Make sure you replace 9.0.0 and 8.9.0 to whatever versions you are using in your installation.). This can lead to problems with modules that are *explicitly* d9 only, as they will not work in this scenario, but it might get you past where you need to be.

  4. Run any pending database updates, required if you update module code and that module needs to update the database, either by visiting update.php in the browser, or with Drush:

    drush updatedb

  5. When complete, restore read-only access to the sites/default directory:

    chmod 755 web/sites/default
chmod 644 web/sites/default/*settings.php
chmod 644 web/sites/default/*services.yml

    If you did run to include core 9.0 as 8.9 make sure to change the entry after a successful upgrade in your composer.json file. Otherwise you won't be able to install any Drupal updates.

    "drupal/core": "^9.0.0",

Things to check when update fails

Upgrading your site you may want to check composer.json for these lines:

"drupal/core":"^8.8.0", -> delete this line
"laminas/laminas-diactoros":"1.8" -> change to "^2"
"drupal/core-dev": "^8.8.0" -> change to "^9"

Upgrading a Tarball-based Drupal 8 site

Upgrading a tarball-based site from Drupal 8 to Drupal 9 with Drush requires an older version of Drush: Drush 8. See Update core via Drush for instructions on how to do this.

As of Drupal 9.4 sites built with tarball or zip file archives will no longer receive the same level of security support for core dependencies. Sites built with tarball or zip files should convert to using drupal/core-recommended to apply security updates more promptly than the above timeframe.

 

Source: https://www.drupal.org/docs/upgrading-drupal/drupal-8-and-higher 

Tags

Comments