Migrate Source CSV

The Migrate Source CSV module provides a CSV source plugin for Drupal's Migrate API, enabling you to import content from CSV files into your Drupal site.

When to Use This Module

Use Migrate Source CSV when you need to:

• Import bulk content from spreadsheets exported as CSV (users, articles, products, taxonomy terms, etc.)
• Migrate data from legacy systems that can export to CSV format
• Populate your site with initial content during site builds or demos
• Regularly sync data from external sources that provide CSV feeds
• Import data from remote locations using stream wrappers (version 3.x only)
• Handle complex CSV formats with custom delimiters, enclosures, or escape characters

Common Use Cases

Importing Users

source:
  plugin: csv
  path: 'public://imports/users.csv'
  ids: [id]
  header_offset: 0
  fields:
    - name: id
      label: 'User ID'
    - name: first_name
      label: 'First Name'
    - name: last_name
      label: 'Last Name'
    - name: email
      label: 'Email'

Creating Content from Product Catalogs

Import product information with references to images and taxonomy terms, where each row in your CSV becomes a node.

Bulk Taxonomy Term Creation

Quickly populate vocabularies with terms from exported spreadsheets, useful for countries, categories, tags, or other classification systems.

Paragraph Entity Migrations

Import structured data into paragraph entities that can be attached to nodes, perfect for complex content layouts.

Key Features & Configuration Options

The module supports various CSV configurations:

• Custom delimiters: Not just commas - use pipes (|), tabs, or any character
• Field enclosures: Handle quoted fields (default is ")
• Header rows: Specify which row contains column names or work without headers
• Multiple IDs: Use composite keys for unique identification
• Stream wrappers (3.x): Access files from public://, private://, remote URLs, or module directories

Version Differences

Version 2.x vs Version 3.x

The difference is in how CSV files are parsed and loaded:

• 2.x uses custom CSV parsing and reading
• 3.x uses the league/csv library for parsing and reading, providing:
  • Support for many more CSV features
  • Reading from file streams (a highly requested feature)
  • Better handling of complex CSV formats
  • More robust error handling

If you're considering updating to 3.x, review the upgrade change record.

Important: If you have csv_serialization installed, update it to version 2.x+ to avoid conflicts with migrate_source_csv 3.x. The underlying CSV reader libraries conflict between csv_serialization 1.x and migrate_source_csv 3.x.

Example Resources

A super simple CSV example using the CSV files from this project's unit tests is available as a reference model. The unit tests demonstrate:

• Standard comma-delimited files with headers
• Custom delimiters and enclosures
• Multi-line field values
• Various data types (text, dates, email addresses)

See the test fixtures for working examples you can adapt to your needs.

Related Resources

Similar Modules

• Migrate Spreadsheet - Supports .ods, .xls, .xlsx, and .csv files
• Migrate Plus - Supports XML and JSON, plus additional migration features
• Migrate Tools - Provides Drush commands and a web UI for running migrations
• Migrate Source UI - Provides a web UI for uploading and importing CSV files.