Preparing a site for upgrade to Drupal 8

Last updated on
7 February 2018

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. Instead, configuration and content entities are migrated from the source site to a clean Drupal 8 site. Refer to the Upgrading from Drupal 6 or 7 to Drupal 8 page for an overview of the process and key differences.

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.

Module inventory of the source site

It is important to understand how your existing Drupal 6 or Drupal 7 site is built before you start your upgrade to Drupal 8.

Identify the core and contributed modules that are enabled on your source Drupal 6 / 7 site. To do this, you can either look at the listed modules on the Modules admin page (Administer > Site building > Modules) or use the Available Updates page at admin/reports/updates.

Write down the complete list of modules enabled on your source site and use this as a checklist to plan your upgrade. For each module, answer the following questions:

  • Do I still need this module on Drupal 8?
  • Has the contributed module moved to Drupal 8 core? For example Views is now part of Drupal 8 core.
  • Does the contributed module have a Drupal 8 version available? If not, do I still need it? Are there other modules that I could use to achieve the same functionality? 
  • Please 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. 

Drupal 8 upgrade web user interface shows a summary of which modules can be automatically upgraded and which ones cannot. Refer to Upgrade using web browser page for more information on this analysis.

Check the Known Issues page

The upgrade path from Drupal 6 / 7 to Drupal 8 is still experimental and some core modules might not have a complete upgrade path. It is recommended to read through the Known Issues page when preparing the upgrade.

Update your Drupal 6 / 7 site to use the latest versions of core and contributed modules

The upgrade process expects you to first update your old site to the latest minor version. If your site is for example running Drupal core 6.35, you need to first update to 6.38.

If you're planning to automatically migrate configuration or content from contributed modules, you are expected to be using the latest versions of them. 

Use the Available Updates page of your Drupal 6 / 7 site at at admin/reports/updates to see if there are updates available.

Pre-requisites for upgrading from Drupal 6 / 7 to Drupal 8

  • A fresh installation of Drupal 8 with the core modules 'Migrate' and 'Migrate Drupal' enabled. If you're upgrading to Drupal 8 using the browser user interface, you will also need to enable 'Migrate Drupal UI' core module.
  • 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 and you must configure the Drupal 8 file_private_path path in settings.php before running the upgrade.
  • If you're upgrading to Drupal 8 using Drush, you will also need  Drush 8 or Drush 9 and three contributed modules.
    • Installation instructions for Drush are included on the page linked above.
    • Install Migrate Tools
    • Install Migrate Upgrade  
    • Install Migrate Plus
    • For more information on the modules listed above, please refer to the list of upgrade modules
    • IMPORTANT: Pay close attention to the compatibility of the module versions and the version of Drupal 8 core you are using. The module pages of the three modules listed above clearly state which version to use.

Enable required core and contributed modules in Drupal 8

The migration process does not automatically install modules on the Drupal 8 destination site. Only migrations relevant for modules installed on both the source and destination site will be executed. Therefore you need to first enable all core and contributed modules on the Drupal 8 site for which you want to migrate configuration and content from the source site.

A couple of examples:

  • If you have the Addressfield module enabled on your source Drupal 7 site and want to migrate the address data, you must enable the Address module on your Drupal 8 site before beginning the upgrade process. This is a good example where the modules do not map 1:1 between Drupal 7 and Drupal 8. However, the D8 Address module provides the migrate plugins that are needed to migrate the data from Drupal 7 Addressfield. 
  • If you have the Drupal 7 core Forum module enabled on your source site, you must enable the core Forum module on your Drupal 8 site before beginning the upgrade process.

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. In fact, it is a common best practice to install Drupal 8 using the Minimal install profile, because the Standard profile introduces its own configuration that you might not want to use. 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

You have two choices to actually execute the migration:

  1. Using the browser user 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 additional modules and it must be run from the command line.