Upgrading is the process of moving your site from a previous major version of Drupal to a newer version, for example from Drupal 7 to Drupal 9. This consists of upgrading the codebase to the appropriate version and then migrating the data from your old site into the new one. Drupal 8 core contains two modules to help facilitate this process: Migrate Drupal and Migrate Drupal UI.

Make sure you understand the difference between updating and upgrading. If you already have a Drupal 8 site and want to move to another minor version, see the Minor Version and Security Updates topic.

If you are on Drupal 8 and you want to upgrade to Drupal 9, a migration is not necessary. See Upgrade to Drupal 9

Should I wait until Drupal 9 is released before upgrading? Because Drupal 9 will be basically Drupal 8 streamlined, trying to skip updating to Drupal 8 will not bring benefits. Skipping Drupal 8 would mean you have less time to execute the upgrade and therefore more risk in your project. Doing the upgrade to Drupal 8 with an eye to Drupal 9 is the best approach. You can already benefit from all the goodness in Drupal 8 then including the easier upgrade paths going forward. Learn more in our Guide to Drupal 9.

Example tasks

  • Upgrade a site from Drupal 6 to Drupal 8
  • Upgrade a site from Drupal 7 to Drupal 8
  • Upgrade a site from Drupal 8 to Drupal 9


The upgrade process, and underlying Migration API, are still evolving. We don't anticipate them changing dramatically even though they are still marked experimental. Beware of any resources that were written before Drupal 8.1.x was released (April 19, 2016) as the system changed considerably in ways that invalidate many of the older articles.

Drupalize.Me resources

Upgrade status generates a report that serves as a sort of checklist to help you determine whether or not your site is ready to be upgraded to Drupal 9. It packs a lot of useful information into a single report. It's worth taking the time to install it on a copy of your Drupal 8 site and seeing what it has to say.

Drupal check, and Drupal rector, are two useful command line tools you can use to help jump start the process of updating your Drupal 8 code to ensure it's compatible with Drupal 9. This post includes some notes about the process I went through while testing them out on some of the Drupalize.Me code base.

More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources

  • Upgrade to Drupal 8 (
    • Community guide to upgrading to Drupal 8. Contains some good background information on why things work the way they do. Also has step-by-step walkthroughs of using both the UI and Drush to run an upgrade migration.
  • Known issues when upgrading from Drupal 6 or 7 to Drupal 8 (
    • The upgrade process is still in development. There are some known incomplete paths, and issues, with the upgrade process which you can keep track of here.
  • The State of Drupal 9
    • Slide deck (with detailed presenter notes) on The State of Drupal 9. The main takeaway is that by keeping your Drupal 8 site up-to-date, you're already preparing for an upgrade to Drupal 9. Also, waiting for Drupal 9 to perform your upgrade has no real benefit.