Skip to main content

wp import

Overview

Import posts, pages, custom post types, terms, and comments from a WXR XML file into WordPress. Requires the WordPress Importer plugin to be active.

What It Does​

wp import runs the XML through the WordPress Importer plugin, inserting content into the destination WordPress database. Author handling is configured via the --authors flag.

Syntax​

wp import <file> --authors=<mode>

Arguments & Options​

FlagDescription
FILEPath to the .xml WXR file to import
--authors=MODEHow to handle authors: create, mapping.csv, or skip
--skip=ITEMSComma-separated items to skip: image_resize, attachment

Author Modes​

ModeBehaviour
createCreate new user accounts for any authors found in the XML
skipSkip content with authors that don't exist on the destination
mapping.csvProvide a CSV mapping file of old → new author logins

Basic Usage​

Import with author creation​

wp import /tmp/export.xml --authors=create

Import skipping unknown authors​

wp import /tmp/export.xml --authors=skip

Import with author mapping file​

# mapping.csv format: old_login,new_login
# e.g.: sarah,sarah_new
wp import /tmp/export.xml --authors=mapping.csv

Prerequisites​

The WordPress Importer plugin must be installed and active:

wp plugin install wordpress-importer --activate

Real-World Scenarios​

Scenario 1: Full content migration​

# Install importer
wp plugin install wordpress-importer --activate

# Import all content, creating authors
wp import /tmp/migration.xml --authors=create

# Verify
wp post list --post_type=post --format=count
wp user list --format=count

Scenario 2: Import with author mapping​

# Create mapping file
cat > /tmp/author-map.csv <<EOF
old_admin,new_admin
sarah.jones,sarah
bob_writer,bob
EOF

wp import /tmp/export.xml --authors=/tmp/author-map.csv

Scenario 3: Import without media processing (faster)​

wp import /tmp/export.xml --authors=create --skip=image_resize

Scenario 4: Import multiple split XML files​

for file in /tmp/exports/*.xml; do
  echo "Importing: $file"
  wp import "$file" --authors=skip
done

Best Practices​

  1. Install the importer plugin first — import will fail without it.
  2. Use --authors=skip when the destination has the same users already.
  3. Use --authors=mapping.csv for migrations where usernames changed.
  4. Run wp search-replace after import if the source URL differs.
  5. Import media separately via rsync of the uploads/ folder.

Post-Import Checklist​

# 1. Check post counts
wp post list --post_type=post --format=count

# 2. Update URLs if domain changed
wp search-replace 'https://old-site.com' 'https://new-site.com' --skip-columns=guid

# 3. Flush permalinks
wp rewrite flush

# 4. Flush cache
wp cache flush

Troubleshooting​

ProblemCauseFix
Error: WordPress Importer not activePlugin missingwp plugin install wordpress-importer --activate
Error: parsing XMLMalformed or corrupted export fileRe-export from source site
Duplicate posts after importImport run twiceCheck with wp post list before re-running
Images show as brokenFiles not copiedSync uploads/ with rsync

Quick Reference​

wp plugin install wordpress-importer --activate
wp import export.xml --authors=create
wp import export.xml --authors=skip
wp import export.xml --authors=mapping.csv
wp search-replace 'https://old.com' 'https://new.com' --skip-columns=guid
wp rewrite flush && wp cache flush

Next Steps​