Import, export and migration overview
3 min read
Mass Custom Fields can move two different kinds of things:
- Definitions: field groups, post types, taxonomies and options pages. A definition describes what exists. Moving it never touches your content.
- Values: what editors typed into the fields of posts, terms, users, comments and options pages. Values are stored in the field group tables, so ordinary WordPress export tools do not see them without help.
Everything lives under WPM Fields › Tools (page slug wpmcf-tools), which has three tabs, plus a few tools that run outside the Tools screen.
Which tool should I use?
I want to... | Use | Moves |
|---|---|---|
Copy field groups, post types, taxonomies or options pages to another site | Definitions | |
Keep definitions in my theme and in Git, and load changes teammates made | Definitions | |
Switch from Advanced Custom Fields | Definitions and values | |
Move posts together with their field values to another site | Values | |
Copy a post (Yoast Duplicate Post or similar) and keep its field values | Values | |
Script any of this on a server or in a deployment | Both | |
Understand why a long job is "running in the background" | n/a |
Field groups registered in PHP code (wpmcf_register_field_group(), wp wpmcf code) are described in Integrations and developer tools.
What a JSON export contains
A file made with Export holds one section per kind of definition:
Section | Kind | Identified by |
|---|---|---|
| Post Types | the post type name |
| Taxonomies | the taxonomy name |
| Options Pages | the page slug |
| Field Groups | the field group key |
It never contains saved field values, user data, license data or settings.
What each method does with existing items
Method | Existing item with the same key |
|---|---|
JSON import | Kept as it is, unless you switch on Replace existing definitions |
Local JSON sync | Replaced, but only for files that really changed |
ACF migration | Field groups already migrated are kept; values are copied again |
WP-CLI import | Same as the JSON import: kept unless you pass |
Nothing in this section ever deletes a definition on the target site. Removing an item is always done in its own screen.
Things to know first
- Everything here needs the manage_options capability, which administrators have.
- Importing a field group creates (or changes) its database table right away. Check the preview first and read Changing a field group safely if you replace an existing group.
- Files larger than 5 MB are refused, everywhere (Tools screen, Local JSON, WP-CLI).
- Field types of the Pro plan (gallery, flexible content, clone, and the other advanced types) cannot be imported on a site without that plan. The preview shows which field group fails and why. See Plans and licensing.
- Failures inside background jobs and file writes are logged under WPM Fields › Settings › Health. See Health and troubleshooting.
Still stuck? Contact support