Warning message

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

Brief overview, and history of automated upgrading to Drupal 8

Last updated on
October 24, 2016 - 13:51


You can easily, and automatically upgrade your existing D6 or D7 site, because Drupal 8 core includes three migration modules designed to accomplish that task.

You create a new D8 site, which you do not modify at all, except that you enable the three core migration modules.

Your existing D6 or D7 site remains completely unaltered and intact.

Although you might hope or expect that your new D8 site will be essentially the same as your old site, with the added benefit of D8's new and improved features, that is not likely to be the case.

You will have to try it for yourself to see whether or not that is true for you, though luckily that is fairly easy to do.

After you have done that, you can examine the results, and determine whether or not you think the immediately apparent errors, (not to mention those that pot-up as you navigate around), lead you to the conclusion that it would be easier to manually copy and paste your old content into a different new D8 site, rather that your trying to correct all the errors, and then settling for the questionably broken nature of an automatically migrated site-- one for which you will always wonder whether problems it gives you in the future are, or are not, related to the migration, as opposed to being problems inherent to D8. Even in the absence of errors, an auto-migrated D8 site is likely to have anomalies that a standard new D8 site does not.

Personally, I have happily resigned myself to copy/paste my 500+ multi-fielded D7 pages, knowing that, though it will take time, I will be working with a fresh D8 site-- one unaffected by a nobly attempted, but inherently flawed auto-migration.

There are enough challenges to learning D8, without my having to wonder whether some left over D7 influence is thwarting my quest to be fully and properly incorporating the full benefit of D8's cutting edge features.

The automated upgrade process using the browser user-interface, in a nutshell

  1. Create a new Drupal 8 site.

    In fact, if you are relatively new to D8, create two. One D8 site for your migration, and one that you can compare it against.

    In other words, I recommend that if you do not already have a Drupal 8 site up and running, you will want to have one alongside the migrated D8 site, so that you can refer to it, and see what an unaltered D8 site looks like, and how it functions, in comparison to your migrated one.

  2. Enable the three D8 core 'Migrate...' modules [On the 'Extend' page, currently near the bottom under the heading 'Core (Experimental)'].

  3. Add "/upgrade" to your site URL, eg.: http://my-d8-site.com/upgrade

  4. On that page, enter your D6/D7 database credentials, found in "settings.php", for example at: [codebase-root]/sites/default/settings.php

  5. Click "Review upgrade". (...)

  6. (...) In no time at all, "Voila." Good luck, my friend.

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.

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

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

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 base class for migrating reference fields

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: