Warning message

Documentation is currently being migrated into the new system. Some pages might be temporary missing, and some guides might appear empty. Thank you for you patience while we are improving Drupal.org documentation.

Upgrading from Drupal 6 or 7 to Drupal 8

Last updated on
August 18, 2016 - 23:55

Brief history and background

Earlier versions of Drupal 7 and Drupal 6 included a built-in update/upgrade mechanism that provided for in-place minor version 'updates' within the same major version of Drupal (from Drupal 7.3 to 7.8, for example), and also for 'upgrades' between major versions of Drupal (from Drupal 6.12 to Drupal 7.4, for example). Both minor-version 'updates', and major-version 'upgrades', required doing updates/upgrades in place-- putting the new codebase on top of the old database.

In Drupal 8, there are two separate systems: one for 'updates' (Eg. from D8.0 to 8.1), and a migration system for 'upgrades' (Eg. from Drupal 6, or Drupal 7, to Drupal 8).

For minor-version 'updating' of an existing Drupal 8 site, you should still use the in-place (update.php) mechanism.

On the other hand, 'upgrading' from earlier major versions of Drupal 6 and Drupal 7 (as well as migrating from other systems; if and when applicable), is done with 'migration'.

This page is about the migration system of 'upgrading'. (Not about minor version 'updates')

The Drupal 8 migration system from Drupal 6, or Drupal 7, that is detailed on this page is, in essence, a migration of both the 'content' and the 'configuration settings' between two independent sites. Implied in this is the fact that you have to create a 'new' Drupal 8 site to accept your old content and configuration settings from D6, or D7.

The migration system is largely inspired by the work of these two modules, which were designed to import things 'into' Drupal 7, as for example from Drupal 5, Drupal 6, or from other Drupal 7 sites:

The Drupal 8 migration system is a much more robust and extensible system than was available in previous major versions of Drupal core.

The three new modules included in Drupal 8 core, 'Migrate', 'Migrate Drupal', and 'Migrate Drupal UI', are currently listed about half-way down the 'Extend' page ('Extend' being the new name for the modules page in Drupal 8), and are under the heading 'Core (Experimental)'. These three modules greatly expand on the functionality of previous versions of the Migrate module in that these D8 modules now handle both site configuration and content.

The Drupal 8 migration process

You might first want to review the page Prepare D6 or D7 for upgrade to Drupal 8: Pre-migration details before you perform your upgrade by either


Process diagram for migration steps

Upgrading from Drupal 6 and Drupal 7 sites is now possible, with support for:

  1. Drupal 6: core + CCK + Link + Email + Phone + ImageCache modules.
  2. Drupal 7: only content, users, taxonomy, blocks, menus, filter formats (more coming soon - #2456259: [META] Drupal 7 to Drupal 8 Migration path).

Migrations that are not yet supported include:

  1. Views (#2500547: Upgrade path for Views from Drupal 6 and 7)
  2. Multilingual content (#2225775: Migrate Drupal 6 core node translation to Drupal 8)
  3. Node, user, entity references (#2447727: Add migrate support for Drupal 6 node & user reference

How to find the migration modules and tools

Name Where is it? What does it do?
Migrate Drupal 8 core module Provides the underlying API for migrating configuration and content to Drupal 8. The migration source may be a different system altogether.
Migrate Drupal Drupal 8 core module Provides the classes specifically needed to migrate configuration and content from a Drupal source site to Drupal 8 as a special case of Migrate.
Migrate Drupal UI Drupal 8 core module (in 8.1+). Also a contributed module for earlier versions of Drupal 8. Provides the tools necessary for performing an upgrade from Drupal 6 or Drupal 7 to Drupal 8 — with a simple user interface (at /upgrade).
Drupal Upgrade Contributed module Provides the migrate-upgrade drush command.
Migrate Tools Contributed module Provides optional drush (migrate-status, migrate-import, migrate-rollback, migrate-stop, migrate-reset-status, migrate-messages, migrate-fields-source) and UI tools for managing your migrations.
Migrate Plus Contributed module Provides APIs for grouping migrations as well as a facility to manipulate incoming source data in migrations as well as code examples to build custom migrations.
Migrate Manifest Contributed module Provides a drush command for running template-based SQL migrations from a manifest file.
Migrate UI Contributed module Provides a user interface for editing and configuring migrations in general (not just Drupal sources).
Migration plugins Within core modules and contributed modules Provide mapping for the configuration and content of the respective module. For example, the migration plugins that handle taxonomy vocabularies and terms are located in the core taxonomy module.

Further Reading

Developer documentation is available for writing your own custom migrations.

Links listed above: