Magento 2 Data Import Tool: Complete Guide

Magento 2 has a built-in data import tool for bulk uploading products, customers, pricing, and inventory through CSV files. Whether you're migrating from another platform or updating thousands of product prices, knowing how this tool works will save you hours of manual entry.

This guide covers the native Magento 2 import functionality: how to access it, what entity types it supports, the CSV format requirements, image import methods, and how to fix common errors. We'll also talk about CLI import limitations (which might change your automation plans).

Accessing the Magento 2 Import Tool

You'll find the import tool in the Admin panel under System > Data Transfer > Import.

Before you start, here are the technical constraints:

One thing that trips up a lot of store owners: files saved with a BOM (Byte Order Mark) cause import failures. When exporting from Excel, save as "CSV UTF-8 (Comma delimited)" and avoid the standard CSV option. I've seen this cause hours of debugging for something that takes 10 seconds to fix.

The system message on the Import page shows your current file size limit. If you need to import larger files, you'll need to increase the upload_max_filesize and post_max_size values in your php.ini, or just split your data into smaller batches.

Supported Entity Types

The native import tool supports six entity types. Each has its own CSV structure.

Orders, categories, CMS pages, and CMS blocks are NOT supported by the native tool. You'll need a third-party extension like Firebear Improved Import & Export for those.

Import Behavior Options

When you select an entity type, you pick an import behavior. This controls how Magento handles records that already exist.

Add/Update (Use This One)

Creates new records or updates existing ones based on SKU (for products) or email (for customers). All fields except the unique identifier can be updated. This is the safest option for most scenarios because it preserves existing data not in your CSV.

Replace

Deletes existing data matching your CSV and creates new records. Adobe's documentation has a warning worth reading:

"Exercise caution when replacing data because the existing product data is cleared and all references in the system are lost. If a SKU in the import data matches the SKU of an existing entity, all fields, including the SKU, are deleted and a new record is created using the CSV data."

Only use Replace when you want a complete data refresh and you're okay losing anything not in your import file.

Delete

Removes entities matching the identifiers in your file. For bulk product removal or customer cleanup.

Error Handling Configuration

Two options here:

• Stop on Error: Halts everything when the first error hits
• Skip error entries: Keeps going, skipping bad rows

You can also set an Allowed Errors Count (default: 10), which is how many errors Magento tolerates before canceling.

For testing new CSV structures, use "Stop on Error" to catch problems fast. For production imports where you expect some invalid rows, "Skip error entries" gets the valid data through while logging problems for later.

Product CSV Format Requirements

Products are the most common import type, and they have the most complex CSV structure.

Required vs Minimum Fields

The only required field is sku. But for a product to actually show up on your storefront, you need more.

Minimum fields for new products to work:

Complete Product Attribute Reference

Here's the full list of standard product attributes for your CSV:

Category Path Format

Categories use a path format with pipe separators for multiple assignments:

Default Category/Gear|Default Category/Gear/Bags

This puts the product in both "Gear" and "Gear/Bags" categories.

Getting the Sample CSV Template

Easiest way to get the right structure: download the sample from Magento itself.

1. Go to Admin > System > Data Transfer > Import
2. Select Products from Entity Type
3. Click Download Sample File

You get a CSV with correct headers and example data for your Magento version. Start from this.

Configurable Product Import

Configurable products (like a t-shirt in multiple sizes and colors) need extra columns to link the parent product to its variants.

Service Data Columns

Configurable Variations Format

The configurable_variations column format:

sku=sku-red-xs,color=red,size=xs,price=10.99,display=1,image=/pub/media/import/image1.png|sku=sku-red-sm,color=red,size=sm,price=10.99,display=1

Variants are pipe-separated. Within each variant, attributes use key=value pairs separated by commas.

The child simple products must exist first. Import simple products, then import the configurable parent referencing those SKUs. Get this order wrong and the import fails silently (annoying, but that's how it works).

Bundle Product Import

Bundle products let customers build their own product from options. They use these columns:

Bundle Values Format

name=Bundle Option One,type=dropdown,required=1,sku=sku-option2,price=10,price_type=fixed

The type can be dropdown, radio, checkbox, or multiselect.

Image Import Handling

Three methods for importing product images. Pick based on your situation.

Method 1: Local Server Images

Most reliable for large image imports.

Default upload directory: <Magento-root>/var/import/images

Steps:

1. Upload images to var/import/images via SFTP
2. In your CSV, use just the filename (not the full path)
3. During import, specify var/import/images in "Images File Directory"

From Adobe's docs:

"For images in the default import folder (var/import/images), do not include the path before the filename in the CSV data."

So your CSV has product-image.jpg, not the server path.

Method 2: External Server Images

Reference images on external servers using full URLs:

Requirements:

• Full URL with https://
• Publicly accessible (no auth)
• PNG, JPG, or GIF

Example:

https://example.com/images/product-image.jpg

Convenient for migrations where images are on the old platform, but this slows down imports significantly. Magento downloads each image during processing.

Method 3: Remote Storage (Cloud)

For stores using Remote Storage with AWS S3 or similar:

Path format: <remote-storage-root>/var/import/images

Configure your remote storage connection first, then use the same structure as local imports.

Image Column Types

Specs:

• Maximum recommended: 25 megapixels (5000 x 5000 px)
• Frontend resizing happens via pub/get.php
• For multiple images per product, add rows with the same SKU

Customer Import

Three entity types: main file only, addresses only, or combined.

Customer Main File Attributes

On collecting birth dates: Adobe recommends reviewing your practices here:

"In keeping with current security and privacy best practices, review the storage and processing of customers' full date of birth (month, day, year). When collected with other personal identifiers (such as full name), it is a potential legal and security risk."

Customer Address Attributes

Advanced Pricing Import

For tier pricing and customer group pricing:

Set up volume discounts ("Buy 10+ and save 15%") and B2B pricing without editing each product.

Step-by-Step Import Process

Step 1: Prepare Your Data

1. Go to System > Data Transfer > Import
2. Select your Entity Type
3. Click Download Sample File
4. Build your CSV from that template
5. Check your file size against the limit shown

Step 2: Configure Import Behavior

1. Pick your behavior (Add/Update, Replace, Delete)
2. Choose error handling
3. Set Allowed Errors Count
4. Configure separators (comma is default)
5. Enable "Fields Enclosure" if your data has special characters

Step 3: Upload the File

1. Click Choose File and select your CSV
2. For product images, specify the Images File Directory

Step 4: Validate and Import

1. Click Check Data to validate
2. Review any errors
3. If validation passes, click Import
4. Watch the progress
5. Check System > Data Transfer > Import History for results

Run validation first. Always. It catches most problems before anything changes.

Common Import Errors and Solutions

The errors you'll see most often:

How to Avoid Errors

• Start from the sample CSV template
• UTF-8 encoding (no BOM)
• Test with 10-20 records before running full imports
• Use "Check Data" every time
• Keep descriptions under 255 characters for safer processing
• No special characters in SKUs or URL keys

Command-Line Import: The Catch

Native Magento 2 does NOT support CLI import.

If you're planning automation through cron or scripts, here's what you're looking at:

Scheduled Import/Export (Adobe Commerce Only)

Adobe Commerce (paid version) has scheduled imports:

• System > Data Transfer > Scheduled Imports/Exports
• Runs via cron, not direct CLI
• Supports FTP/SFTP sources
• Same entity types as manual import

Third-Party Extensions

For actual CLI capability, Firebear Improved Import & Export is the go-to:

php -f bin/magento import:job:run JOB_ID
php -f bin/magento import:job:enable JOB_ID
php -f bin/magento import:job:disable JOB_ID

M2IF (Free Open-Source Option)

The M2IF framework gives you:

• CLI import with Magento 2 standard CSV format
• Custom import applications
• Extensible architecture

Build Your Own

You can create a custom module with:

• A CLI command (e.g., bin/magento yourmodule:import-products)
• Magento's built-in import processor classes
• Your validation and transformation logic

Maximum flexibility, but you need dev resources.

When Third-Party Extensions Make Sense

The native tool handles occasional bulk updates fine. Consider an extension if you:

• Need to import orders, categories, or CMS content
• Want CLI/cron automation
• Work with XML, JSON, or Excel (not just CSV)
• Pull from external sources like Google Sheets or APIs
• Are migrating from Magento 1, Shopify, or WooCommerce
• Have files bigger than 2MB regularly
• Need data transformation during import

Extensions like Firebear add:

• Orders, categories, CMS, attributes, URL rewrites
• CSV, XML, JSON, Excel XLSX, ODS formats
• Google Sheets, Dropbox, OneDrive, REST/SOAP API sources
• Cron scheduling and CLI
• Migration presets for platform switches

Building Customer-Facing CSV Uploads

The native tool is admin-only. If customers or suppliers need to upload CSVs (like a vendor uploading their catalog), you need a different approach.

ImportCSV provides embeddable components for:

• User-friendly column mapping
• Real-time validation with clear errors
• Large files without server changes
• Any backend: Magento APIs, custom databases, third-party services

Useful for headless Magento or custom storefronts where users need self-service uploads.

Summary

Magento 2's import tool at System > Data Transfer > Import handles products, customers, pricing, and inventory via CSV.

Six entity types work natively: Products, Advanced Pricing, Customers Main File, Customer Addresses, Customers and Addresses, Stock Sources.

Format matters. UTF-8 without BOM. Download sample templates. Validate before importing.

Three image methods: local (var/import/images), external URLs, or cloud storage.

No native CLI import. You need Adobe Commerce scheduled imports, Firebear, M2IF, or custom dev.

Use Add/Update behavior unless you specifically need Replace or Delete.

Validate first. The "Check Data" button catches most errors before changes happen.

For anything beyond occasional bulk updates, evaluate extensions against your needs. The native tool is fine for straightforward imports run by admins, but it wasn't designed for automation or complex data flows.