Last updated August 24, 2017

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 8. 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.

Example tasks

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


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

  • Introduction to Migrations with Drupal 8
    • The upgrade process is built on the Migrate API. Familiarizing yourself with the basic concepts and terms of the migration system will help you better understand how to perform an upgrade.
  • Prepare for a Drupal-to-Drupal Migration
    • There's a lot more to upgrading than just running the right script. Create a plan, and understand what is involved in executing a successful upgrade.
  • Drupal-to-Drupal Migration with the UI
    • Learn how to use the Migrate Drupal user interface to perform the data migration component of an upgrade.
  • Drupal-to-Drupal Migration with Drush
    • For anything other than the most basic upgrades, we recommend learning how to use Drush to perform the data migration from the command line. It's both faster and more flexible.
  • Custom Drupal-to-Drupal Migrations
    • The migrations used as part of the standard upgrade process all follow a very specific pattern that can not be altered. If you want to tweak either what data is migrated, or alter the data in the process, you'll need to use the Migrate Plus module and learn how to run custom upgrade migration. Pro tip: You'll probably want to do this for anything other than a super basic upgrade. It's worth learning just for how much easier it'll be to debug upgrades.
  • Importing Data with Migrate API topic
    • This is the upgrade tool that is in Drupal 8 core.

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.