Upgrade using Drush

Last updated on
24 November 2016

Getting the right Drush version

Make sure you are using the latest version of drush which you must get from Composer or Github. If using the Github version, you will still need Composer to download the dependencies. Drush from Drupal.org/PECL/Pear/etc. are likely out of date.

For Acquia Dev Desktop users, you can update Drush using Composer by launching a command prompt in Dev Desktop and running the command:
[c:\your_path_to_acquia]\drush\composer global require drush/drush:dev-master

To check your version of Drush drush --version

Required Drupal modules

To migrate using Drush you need to download and enable the Migrate Upgrade, and Migrate Plus contributed modules. You will also need Migrate Tools if you plan on doing more than running a one-time complete upgrade. Use the 8.x-2.x release of these modules for compatibility with Drupal core 8.1.x.

Run full or single migration using migrate-upgrade

Migrate Tools will add Drush Migrate commands, like drush migrate-status (ms) and drush migrate-import (mi). If you enable this module and try drush migrate-status without doing anything with the Migrate Upgrade module you won't see any migrations available to run. That's because the individual migrations are created dynamically based on the source database you set up. Since Migrate has no idea yet what source to use, no migrations have been created.

To solve that we need the Migrate Upgrade module. Migrate Upgrade comes with a Drush command drush migrate-upgrade. This module does two things:

  1. It will generate migrations for your site, based on migrate_drupal's migration templates and your configured source site. For instance, the d6_book migration is only created if the Book module is enabled on both your Drupal 6 and Drupal 8 sites.
  2. It executes every created migration, in dependency order (because migrations can depend on other migrations -- for instance, migrating nodes depends first on migrating users, so Migrate will ensure that the user migration runs before the node migration).

However, for more control, you will probably want to pass the --configure-only option to migrate-upgrade, so it will only perform the first step of creating the migrations:

drush migrate-upgrade --legacy-db-url=mysql://user:password@server/db --legacy-root=http://mydrupal6site.com --configure-only 

After running migrate-upgrade with the --configure-only parameter, you run migrate-status to see the list of possible migrations:

drush migrate-status 

Then you can review and selectively execute these migrations. To perform the migrations individually run:

drush migrate-import {migration name} 

To perform all the migrations in the list, run:

drush migrate-import --all 

Run specific migrations using migrate-manifest

It is also possible to use a manifest file to set up a specific set of migrations. This lets you run groups of migrations in a reproducible manner. For this method, you also need the Migrate Manifest module. When you have all the components set up, you can get the complete list of available migrations by running:

drush config-list|grep migrate 

Then you need to create a valid YAML file and it will look like the following code sample. You only need to list the ones you need, but it will ask you to add any migrations that are needed to resolve any dependencies. Migrations can be listed in any order and migrate will sort them based on the dependencies.

# user 
- d6_user 
- d6_user_profile_field 
- d6_user_profile_field_instance 
- d6_user_profile_entity_display 
- d6_user_profile_entity_form_display 
- d6_profile_values:user 
- d6_filter_format 
- d6_user_role 
- d6_user_picture_entity_display 
- d6_user_picture_entity_form_display 
- d6_user_picture_file 
- d6_user_picture_field 
- d6_user_picture_field_instance 

# taxonomy 
- d6_taxonomy_vocabulary 
- d6_taxonomy_settings 
- d6_taxonomy_term 

# nodes 
- d6_node 
- d6_node_revision 
- d6_node_type 
- d6_view_modes 
- d6_filter_format 
- d6_field_instance_per_form_display 
- d6_field_instance_widget_settings 
- d6_field_formatter_settings 
- d6_field_instance 
- d6_field 
- d6_field_settings 
- d6_node_settings 
- d6_cck_field_values:* 
- d6_cck_field_revision:* 

# taxonomy fields 
- d6_term_node_revision 
- d6_term_node 
- d6_vocabulary_entity_display 
- d6_vocabulary_entity_form_display 
- d6_vocabulary_field_instance 
- d6_vocabulary_field 

# blocks 
- d6_block 
- d6_menu 

# custom blocks 
- d6_custom_block 
- d6_filter_format 

# book 
- d6_book 
- d6_book_settings 

# file migrations are configurable, see https://www.drupal.org/node/2257723 
- d6_file: 
      conf_path: sites/assets 
      source_base_path: destination/base/path 
      destination_path_property: uri 

Call this file manifest.yml and place it in the root of your Drupal 8 directory. If you do not have permission to put it into the root you can put it elsewhere if you reference the file path within the drush command below.

Make sure that modules used by your listed migrations exist on your Drupal 6 site (e.g.: field module for d6_field etc.) Otherwise, there will be some errors and the following command might not run properly since drush tries to migrate everything that you put in manifest.yml and won't simply skip the missing parameters.

Then, from the terminal, run the following command to migrate (replacing the database credentials and database name appropriately):

drush migrate-manifest --legacy-db-url=mysql://d6user:d6pass@localhost/drupal_6 manifest.yml 

Notes for Acquia Dev Desktop users

If you use Acquia Dev Desktop and have your Drupal 6 site in Dev Desktop, the default database credentials are drupaluser with an empty password and the 33067 port for the database on the IP address. Altogether that leads to --legacy-db-url=mysql://drupaluser:@ in the commands assuming the database name is drupal_6. Run drush status if you are having trouble connecting in order to verify these values.

Reference of Drush migration commands

migrate-upgrade (no alias)

Provided by the Drupal Upgrade project. Use this to run a upgrade from Drupal 6/7 to Drupal 8. This command will generate migration configurations (from migration templates) based on the source site's configuration and content and then run all migrations in the proper order (based on dependencies).

Basic example

drush migrate-upgrade --legacy-db-url=mysql://user:password@server/db --legacy-root=http://mydrupal6or7site.com 


  • legacy-db-url: Database connection information for the source database.
  • legacy-db-prefix: Database table prefix for the source database.
  • legacy-root: Path to the source site, this is used to transfer content from the files directory. If the files are private then a local file path must be specified, for public flies http(s) will work as well.
  • configure-only: Use this to create migration configurations only. When this option is set, migrations will **not** be run.

migrate-status (ms)

Provided by the Migrate Tools module.

migrate-import (mi)

Provided by the Migrate Tools module. Use this to perform one or more migration processes. This is normally used with custom migrations from non-Drupal sources. For example, if you've created and imported a custom migration configuration, this command can be used to run it.

Basic example

migrate-import migration_id_1,migration_id_2 


  • all: Run all migrations currently configured.
  • group: Run all migrations belonging to a particular group.
  • limit: Limit on the number of items to process in each migration.
  • feedback: Frequency of progress messages, in items processed.
  • idlist: Comma-separated list of source IDs to import.
  • update: Migrate new items as well as previously migrated items that have been updated on the source.
  • force: Force an operation to run, even if all dependencies are not satisfied.

Common use cases

  • When migrate-upgrade --configure-only is used, configuration entities are created. Since Drupal 8's default behavior is to not allow existing configuration entities to be overwritten, migrate-upgrade cannot be used to run a migration after migrate-upgrade --configure-only is used. Use migrate-import instead.
  • When a custom migration is created and imported (either via the configuration management UI or drush config-import), use migrate-import to run the migration.

Pro tip: If you've imported a custom migration configuration and you need to update it and re-import it, use the Configuration Update Manager module.

migrate-rollback (mr)

Provided by the Migrate Tools module.

migrate-stop (mst)

Provided by the Migrate Tools module.

migrate-reset-status (mrs)

Provided by the Migrate Tools module.

migrate-manifest (no alias)

Provided by the Migrate Manifest module.

migrate-messages (mmsg)

Provided by the Migrate Tools module.

migrate-fields-source (mfs)

Provided by the Migrate Tools module.