Preparing an upgrade

Last updated on
5 May 2017

Prior to upgrading your Drupal 6 or Drupal 7 site to Drupal 8, it is recommended that you take a few steps to ensure the process will be smooth and have the desired results.

Unlike previous major version upgrades of Drupal core, the Drupal 8 upgrade process does not upgrade the source site in-place. Rather, a new Drupal 8 instance pulls in configuration and content from the source site. Even though the upgrade does not modify the source site in any way, it's recommended that it is not performed on a live site. It's a good idea to use a backup of your live site to ensure a consistent database state (no writes to the database while the migration is running), and to prevent any performance impact on the live site.

A major release upgrade expects you to first update to the current minor release prior to applying the major release update. If 6.38 is the current version of Drupal 6, and your site is running 6.35, you would first need to update to 6.38.


  • A fresh installation of Drupal 8 with the core module Migrate Drupal enabled.
  • Access to the Drupal 6 or 7 database from the host where your new Drupal 8 site is.
  • Access to the source site's files. If only public files are used, they will be accessible through the site's address. If private files need to be migrated, the files directory needs to be directly accessible to the new Drupal 8 site.
  • The Migrate Upgrade module installed and enabled on the Drupal 8 site.
  • If you plan on running the upgrade from Drush, you’ll need Drush 8.
  • If you will be migrating private files from Drupal 7, you must configure the Drupal 8 file_private_path path in settings.php before running the upgrade.

Enable required modules

The migration process does not install modules on the Drupal 8 destination site and only migrations relevant for modules installed on both the source and destination site are run. Therefore prior to running the migration, you need to enable all modules on the Drupal 8 site for which you want configuration and content upgraded from the source site. For example, if you have the Book module enabled on your source site and want to keep your Book hierarchies, you must enable the Book module on your Drupal 8 site before beginning the upgrade process. Also note that the Drupal 6/7 modules do not necessarily map one to one to Drupal 8 modules. For example, the Block module in Drupal 6 and 7 was separated into the Block and Custom Block modules in Drupal 8.

Do not configure the Drupal 8 site

Keep in mind that the upgrade process will overwrite configuration on the Drupal 8 site, so do not do any configuration of the Drupal 8 site until after the upgrade process is complete. This means you do not have to create all the content types and fields manually before running this upgrade. The Migrate module will create them as a part of the migration process. This is different than the way Migrate worked in Drupal 7 and earlier, where you had to have all the content types and fields prepared and ready before running Migrate.

Do not create content on the Drupal 8 site

The upgrade process maintains the unique identifiers from the source site. For example, if a user account had the unique ID 2 on the source site (thus was at the relative URI /user/2), after upgrade the same user account will be at /user/2 on the Drupal 8 site. If you were to create a user account on the Drupal 8 site beyond the default administrator account, it would be assigned user ID 2 - then, when running the upgrade process, the account from the source site with user ID 2 would overwrite it. This applies to user accounts, taxonomy terms, and node content, as well as pretty much any other kind of content with numeric IDs from your source site.

To avoid data loss, do not manually create anything on the Drupal 8 site until all your source content has been fully imported.

Performing the upgrade

Going forward, you have two choices to actually execute the migration:

  1. Using the Migrate Upgrade interface. This is the easier method and it can be done through the user interface of the Drupal 8 site. However it offers less control over the migration.
  2. Using Drush. This is more robust and faster, and allows selective migration. But it requires an additional module and it must be run from the command line.