Upgrading from Drupal 6 or 7 to Drupal 8

Last updated on
28 March 2017


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 may not 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 any errors you may have found 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 than trying to correct all the errors.

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. If "/upgrade" returns a 404 error page, please confirm you have enabled the 'Migrate Drupal UI' module.

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

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

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

Start by a review of the pages Preparing an upgrade and Known issues when upgrading from Drupal 6 or 7 to Drupal 8. When you have meet all the requirements, such as having the password to the Drupal 6 or Drupal 7 database, and there aren't any known issues that will prevent you from upgrading, you are ready to upgrade. You can perform your upgrade by either

Process diagram for migration steps

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 a simple user interface (at /upgrade) for performing an upgrade from Drupal 6 or Drupal 7 to Drupal 8
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: