Preparation

Prior to upgrading it is recommended that you take a few steps to ensure the process will be smooth and have the desired results.

When upgrading from Drupal 6 or Drupal 7 configuration and content entities are migrated from the source site to a clean Drupal site. Refer to the Upgrading from Drupal 6 or 7 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.

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 10?
• Has the contributed module moved to core? For example Views is in core since Drupal 8.
• Does the contributed module have a Drupal 10 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 10 or higher modules. For example, the Block module in Drupal 6 and 7 was separated into the Block and Custom Block modules since Drupal 8. 

The Drupal 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.

You can use the Upgrade Status module to check the list of projects you have installed, and show their availability.

Check the Known Issues page

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 #

• A fresh installation of Drupal with the core modules 'Migrate' and 'Migrate Drupal' enabled. If you're upgrading 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 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 destination site and you must configure the file_private_path path in settings.php before running the upgrade.
• If you're upgrading to Drupal 10 using Drush, you need to download and enable the following contributed modules.
  • Installation instructions for Drush are included on the page linked above.
  • Migrate Upgrade: Provides Drush support for upgrading from Drupal 6 or 7.
  • Migrate Plus: Provides extensions to core migration framework functionality.
  • 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 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

The migration process does NOT automatically install modules on the 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 destination 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 destination site before beginning the upgrade process. This is a good example where the modules do not map 1:1 between Drupal 7 and later versions of Drupal. However, the 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 destination site before beginning the upgrade process.

Do not configure the destination site

Keep in mind that the upgrade process will overwrite configuration on the destination site, so do not do any configuration of the destination 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 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 destination 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 URL path /user/2), after upgrade the same user account will be at /user/2 on the new site. If you were to create a user account on the new site beyond the default administrator account (UID 1), it would be assigned user ID 2. This way, when running the upgrade process, the account from the source site with user ID 2 would overwrite the manually created, already existing user account. This logic applies to all kind of content with numeric IDs, not only user accounts, but also node content, taxonomy terms, etc.

To avoid data loss, do not manually create anything on the destination 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. 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.