Topic
Last updated August 24, 2017

The Drupal 8 Migrate API and related tools are used to import data such as content, users, and configuration values into Drupal. The system consists of three core modules: Migrate, Migrate Drupal, and Migrate Drupal UI. A growing number of contributed modules also aid in writing and executing a migration. In Drupal 7 the migration API is provided by the Migrate contributed module.

As a developer you'll use the Migrate API in Drupal 8 to write migration plugins that extract data from a defined source, transform it to match with your Drupal data model, and then load it into Drupal via the Entity or Config APIs. You'll then use one or more contributed modules to execute, rollback, and debug your data migration.

Example tasks

  • Import data from a CSV file, MySQL database, or other source into Drupal
  • Migrate from WordPress or another CMS to Drupal
  • Provide an update path for users of your module when porting it to Drupal 8

Confidence

The Migration API in Drupal 8 changed significantly between 8.0.x and 8.1.x. Parts of the API are still experimental and continue to evolve, though we doubt they'll change significantly again. If you're doing anything with migrations we recommend using the latest stable version of Drupal 8.x.

Drupalize.Me resources

Our extensive migration guide covers everything you need to know to get started writing, executing, and debugging Drupal 8 migrations. We recommend the following starting points:

  • Introduction to Migrations with Drupal 8
    • Start here if this is the first time you've used Drupal 8's migration tools
  • Write a Custom Migration
    • Use this if you've worked with migrations before and are just looking for a refresher on how to write a migration YAML file or want some examples to copy and paste.
  • Run a Custom Migration
    • Use Drush to run a custom migration, rollback a failed migration, and debug an in-process migration.
  • Learn to write custom source plugins and process plugins
    • Source plugins allow you to customize what data is extracted from an existing source, or add entirely new data sources. Process plugins allow you to transform data during an import. If you're providing an update path for an existing module you'll likely need to write a source plugin.
  • Upgrade to Drupal 8 topic
    • Our resource page for upgrading your site using the Migrate API.

For Drupal 7 migrations check out our series Importing Data with Migrate and Drupal 7, which covers the Drupal 7 Migrate module, the precursor to the Migrate API in Drupal 8.

More Guides

We have guides on many Drupal skills and topics.

Explore guides

External resources

  • Migrate API guide (drupal.org), and Migration API documentation (api.drupal.org)
    • Drupal.org contains documentation about concepts, while api.drupal.org contains implementation details. Use this to locate documentation about the code that makes up the Migrate API, as well as examples of how to configure and use common destination and process plugins.
  • Migrate Plus module (drupal.org)
    • The Migrate Plus module contains some essential additional tools for working with migrations, many of which will likely be included in core in future versions. It also contains two carefully documented submodules that provide examples of implementing migrations in code. Use this for the additional enhancements and if you like to learn by reading through example code.
  • Drupal 8 Migrations by Example (2017.tcdrupal.org)
    • Presentation covering the concepts and terminology of the migrate system followed by some examples including populating address, date, image, and file fields. Watch this presentation to get an overview of concepts used by the system, and get some insight into how two developers have used the migrate API on various real-world projects.
  • Join the #drupal-migrate channel on IRC or Slack

There are so many different permutations of things that someone might want to migrate that it would be impossible for any guide to cover all of them. We'll keep a running list of some of our favorite examples below. Use these resources to see examples, usually with code, of how someone else solved a specific task with the Migrate API.