Importing, Exporting and Migrating

Tools > Export (wp-admin/export.php, capability export, which Administrators have) generates a WordPress eXtended RSS (WXR) file: an RSS 2.0 document with extra elements in the http://wordpress.org/export/1.2/ namespace. The screen offers:

Download Export File streams the XML to the browser. Large sites may hit the PHP max_execution_time or memory limit here, which is when wp export is the better tool.

The exported file for the two Lumen Press books starts like this (shortened; the date line and IDs depend on the site):

Source: WordPress Documentation: Tools Export screen

Points worth knowing about the format:

wp export (part of WP-CLI since its early versions, now in the wp-cli/export-command package bundled with WP-CLI 2.12.0) builds the same WXR from the command line, without browser timeouts, and splits large exports into files of --max_file_size megabytes (15 by default, -1 for no limit). Its filters mirror the screen and add a few: --post_type, --post__in (with --with_attachments to keep the attachments of those posts), --start_id, --author, --start_date/--end_date, --post_status, --category, --max_num_posts, --skip_comments and --include_once (put terms and menus only in the first of several files). The file name follows --filename_format, default {site}.wordpress.{date}.{n}.xml.

Source: WP-CLI Commands: wp export

Tools > Import (wp-admin/import.php, capability import) lists the importers WordPress.org offers. None of them is part of core: each row has an Install Now link that installs a plugin from the directory, after which the row’s link becomes Run Importer. The one for WXR files is the WordPress Importer (wordpress-importer), maintained by the WordPress project. Version 0.9.7 (October 2026) requires WordPress 5.2 and PHP 7.2; its directory page still marks it as tested only up to 6.8, which produces the "not tested with the latest 3 major releases" warning even though it is the official importer. Recent versions changed a lot:

Running it from the admin takes four steps:

wp import drives the same plugin. It refuses to run until the plugin is installed and active:

Source: WP-CLI Commands: wp import

--authors is required and takes create (create the missing users), skip (no mapping; content goes to the user running the command) or the path of a CSV file. With a path that does not exist yet, WP-CLI writes the file and stops, so it can be edited:

Source: WP-CLI Commands: wp import

Editing the second column (for example admin,lena.catalogue) and running the same command again imports with that mapping. --skip=attachment leaves out attachments and --skip=image_resize skips generating intermediate sizes, which saves time on large imports (run wp media regenerate later). The command reference also lists --rewrite_urls, --importer and --source-dir (look for attachment files in a local directory before downloading them), but they are not in a stable release yet: WP-CLI 2.12.0 answers unknown --rewrite_urls parameter, and they need a nightly build (wp cli update --nightly).

The Lumen Press runs above and the full-site import that followed exposed the importer’s behaviour that matters in practice:

The WordPress Importer has filters that a site can set from a must-use plugin, for example to stop administrators from creating accounts through imports on the Lumen Press production site:

Source: WordPress Importer plugin

import_allow_fetch_attachments returning false disables downloading attachments altogether. These filters govern the admin importer screen. wp import --authors=create creates users itself: with this must-use plugin active, the WP-CLI run above still created tom.author. Protect the command line by controlling who can run WP-CLI on the server.

Importing is a privileged operation. A WXR file can contain any post type, any meta and any author e-mail, and the attachment step makes the server download URLs named in the file. Import only files from a trusted source, never a file a third party sent, and on a staging copy first.

Core does not need to be copied: install the same WordPress version on the target (wp core download --version=7.1.3 or the matching container image) and copy only what is site-specific:

Projects whose code lives in Git deploy themes and plugins from the repository and copy only the uploads (see Deployment and CI/CD). Between the two Lumen Press containers the uploads travelled as an archive:

Source: Advanced Administration Handbook: Migrating WordPress

On real servers rsync -a over SSH does the same incrementally, which allows a first copy before the freeze and a short final sync. Files must end up owned by the web server or deploy user with 644/755 permissions (see File Permissions and Filesystem).

wp db export runs mysqldump (or mariadb-dump) with the credentials of wp-config.php and accepts extra dump flags; wp db import loads a dump through the mysql client. Neither needs a working site URL, which makes them safe to use before the URLs are fixed.

Source: WP-CLI Commands: wp db export

The imported database still says the site is at the old address, and it replaces the target’s whole state, including the list of active plugins: the WordPress Importer, active on the target before, was inactive afterwards because it had not been active on the source. The dump contains user e-mails and password hashes; keep it out of the web root, transfer it encrypted and delete it after the move. Large dumps are better compressed (wp db export - | gzip > lumen.sql.gz), and --exclude_tables can leave out log tables that plugins fill. phpMyAdmin or a host’s control panel can export and import too, but they are subject to PHP upload and time limits that WP-CLI does not have.

WordPress stores absolute URLs: home and siteurl in the options table, links and image URLs inside post_content, URLs in widget, theme and plugin settings, and user profile URLs. These must change when the domain changes, and many of them are inside PHP-serialized values. A serialized string records its own length, so a plain SQL replacement that changes the length corrupts it. The Lumen Catalog settings show the effect:

Source: Advanced Administration Handbook: Migrating WordPress

The string is 30 characters long but still declared as s:36, so unserialize() fails and get_option() returns false: the plugin silently falls back to its defaults. The same happens to widgets, theme mods and page-builder data.

wp search-replace unserializes each value, replaces inside it (recursing into arrays and objects), and serializes it again. Run it with --dry-run first:

Source: WP-CLI Commands: wp search-replace

The Type column shows the strategy: columns without serialized data are updated with a fast SQL query, those that contain serialized values (home, siteurl and the Lumen Catalog settings here) go through PHP. The options that matter:

Tables without a primary key are skipped. Search for the most specific string that is safe: https://old-domain catches links but not protocol-relative //old-domain URLs or a bare host name in plugin settings, while replacing the bare host may also hit e-mail addresses (editor@lumenpress-books.test). A second pass with --dry-run for the bare host shows what is left. Replacing http:// with https:// on the same domain is the same operation.

--export combines the replacement and the dump in one step on the source, which leaves the source untouched:

Source: WP-CLI Commands: wp search-replace

The exported file starts every table with DROP TABLE IF EXISTS and CREATE TABLE, so it replaces the target’s tables.

The GUID rule. The guid column of wp_posts is a permanent identifier that feed readers use to decide whether an item is new; it looks like a URL but is not a link. The official migration guide says never to change it, so every replacement above skips it. After the move the books kept https://lumenpress-books.test/books/the-lantern-keeper/ as GUID while their permalinks became https://lumenpress.test/books/the-lantern-keeper/. Code must never use the GUID as a link; wp_get_attachment_url() and get_permalink() build URLs from the current settings.

Without shell access, the migration guide names serialization-aware tools that run inside WordPress (the Better Search Replace plugin, for example) or the standalone interconnect/it script. A standalone script left in the web root is a remote database editor; delete it as soon as the replacement is done.

Two options define where WordPress lives, both edited in Settings > General:

Both carry the scheme and no trailing slash. A wrong value there locks everyone out, because the login form then redirects to an address that does not answer. The official ways back in, from the most to the least preferred:

Source: Advanced Administration Handbook: Migrating WordPress

The constants change what WordPress reports and generates, not what is stored:

Source: WP-CLI Commands: wp config set

The fields on Settings > General can no longer be edited while the constants are defined. Content still contains the URLs that were stored, so the constants are not a substitute for wp search-replace; they are a way to pin the URL per environment (in containers, from environment variables) or to get back into a broken site. Remove them, or keep them deliberately, but do not forget them: a staging copy whose wp-config.php was cloned with production’s WP_HOME redirects to production.

The other documented methods are last resorts:

None of these changes the site URL on a Multisite network (see below).

Source: WP-CLI Commands: wp rewrite flush

wp rewrite flush --hard also writes .htaccess, but under WP-CLI it warns "Regenerating a .htaccess file requires special configuration" because the CLI cannot detect mod_rewrite; it needs apache_modules: [mod_rewrite] in wp-cli.yml. Saving Settings > Permalinks once in the browser does the same. Then check, before switching DNS (a hosts-file entry pointing the domain at the new server lets the team test the real URL):

Older books suggest a plugin or a host tool for every migration and describe moving wp-config.php or changing ABSPATH as part of it. A host’s migration tool or a backup plugin is a valid choice, but it performs the same steps: copy, import, serialization-aware replace. ABSPATH is computed by wp-load.php and is never edited.

A migration is a common moment to change the table prefix, for example when the target database holds several sites, or to consolidate on Lumen Press’s lp_. Changing $table_prefix alone makes WordPress start the installer, because the prefix also appears inside data (see Database Schema). The full change renames the 12 single-site tables and the keys that embed the prefix:

Source: Advanced Administration Handbook: Migrating WordPress

Run it on a backup-protected copy, then set $table_prefix = 'lp_'; in wp-config.php. On the test site the administrator kept the administrator role and manage_options, and the user meta keys became lp_capabilities and lp_user_level. Plugin tables (wp_lumen_stock_log and similar) need renaming too, and the LIKE 'wp\_%' update assumes no plugin stores an unprefixed meta key that happens to begin with wp_; list the keys first with SELECT DISTINCT meta_key FROM lp_usermeta WHERE meta_key LIKE 'wp\_%'.