Export and Import ACF Field Groups as JSON: Local JSON and WP-CLI

This article is a localized edition of the Japanese original. Read the Japanese original

Advanced Custom Fields (ACF) field groups have many settings, and rebuilding them by hand on another site easily leads to missing or mismatched options. ACF can write field group settings out as a JSON file and load that file into another site. This article walks through exporting and importing in the admin, "Local JSON," which syncs with JSON files stored in your theme, and doing the same with WP-CLI. Screen labels are based on ACF 6.x as of October 2026.

Choosing between the three methods

With every method, the JSON contains only the field group settings. The values entered for each post are stored in post meta and similar places in the database, so they are not in the JSON. To move the values as well, migrate the database or use the WordPress export feature separately.

Export JSON from the Tools screen

1. Open "Tools" (ツール in the Japanese UI) from the ACF menu in the admin
2. In the export section, check the field groups you want to export
3. Click "Export As JSON"

Button names are given with ACF's English labels. In an admin displayed in Japanese, they appear translated. The selected field groups download as a single .json file. Depending on your ACF version, you can also select post types, taxonomies, and options pages (ACF PRO) on the same screen.

"Generate PHP" on the same screen shows PHP code that registers the field groups instead of JSON. If you paste that code into a theme or a custom plugin, the field groups load without being stored in the database. Field groups registered with PHP can't be edited in the admin, though, so this suits cases where you want to lock the settings.

Import JSON from the Tools screen

On the destination site, do the following.

1. Open ACF "Tools"
2. In the import section, choose the exported .json file
3. Click "Import JSON"

Field groups are identified by a key that starts with group_. If the destination already has a field group with the same key, it is overwritten with the imported content. In case the destination has its own changes, back up its database before importing.

wp db export before-acf-import.sql

After importing, check the number of field groups and their "Location" rules (which post types or templates they appear on) in the field group list, and confirm the fields show up on the post edit screen.

Manage settings as files with Local JSON

Local JSON writes a field group's settings to a JSON file in your theme every time you save it. You can manage the files in Git or deploy them to another environment. ACF also loads settings from these files at startup, which reduces database queries.

How to turn it on

Create a folder named acf-json in the active theme (the child theme if you use one) and make it writable by the web server.

cd wp-content/themes/your-child-theme
mkdir acf-json
# Make it writable by the user PHP runs as (example: www-data)
sudo chown www-data:www-data acf-json
chmod 755 acf-json

Once the folder exists, open each field group in the admin and click "Update." A JSON file named after the key, such as group_xxxxxxxx.json, is created. Existing field groups don't become files until you update them. The official ACF documentation recommends placing an empty index.php in this folder so its contents can't be listed.

Sync in another environment

When you deploy the files in the acf-json folder to another environment, a sync tab ("Sync available") appears above the ACF field group list. Field groups that are not in the database yet, and field groups whose JSON modified value is newer than the database, become available to sync. Select them in the list and sync to write them to the database.

If you edit a JSON file by hand and don't update its modified value, it won't be treated as available to sync. Where possible, make setting changes in the admin and deploy the files it writes.

Change the save and load locations

To keep the JSON in a custom plugin instead of the theme, change the save and load locations with filters. This example uses an acf-json folder inside the plugin's folder.

<?php
/**
 * Plugin Name: My ACF JSON
 */

// Change the save location
add_filter( 'acf/settings/save_json', function ( $path ) {
	return plugin_dir_path( __FILE__ ) . 'acf-json';
} );

// Add it to the load locations
add_filter( 'acf/settings/load_json', function ( $paths ) {
	$paths[] = plugin_dir_path( __FILE__ ) . 'acf-json';
	return $paths;
} );

If you change only the save location and don't add it to the load locations, ACF won't load the JSON it saved. Use the two filters as a pair. Since ACF 6.2, the acf/json/save_paths filter also lets you set a different save location per field group.

Export and import with WP-CLI

According to the official ACF documentation, ACF 6.8 and later include the wp acf json command (WP-CLI 2.0 or later is required).

# Check the ACF version (the free version's slug is advanced-custom-fields)
wp plugin get advanced-custom-fields --field=version

# Show which items need syncing
wp acf json status

# Sync Local JSON changes to the database
wp acf json sync

# Export all items to a directory
wp acf json export --dir=./exports/

# Import a JSON file
wp acf json import ./acf-export.json

If you use ACF PRO, the plugin slug is advanced-custom-fields-pro. For arguments that narrow down what gets exported, check wp help acf json export for your installed version.

Older tutorials sometimes show commands like wp acf export. Those come from a separately distributed extension package, not from ACF itself. ACF versions before 6.8 don't have the wp acf json command.

Common pitfalls when migrating

• Renaming a field hides its values: Values are stored in post meta under the field name (name). If you rename a field during the migration, it no longer connects to the existing values.
• Don't change keys: The keys of field groups and fields (group_…, field_…) decide syncing and overwriting. Keep them unchanged even when you edit the JSON by hand.
• Check that Location rules fit the destination: If a rule targets a specific page or category, its ID may differ on the destination. Review the rules after importing.
• Use the same ACF version: If you import into an older ACF than the source, settings added in newer versions may not be handled.

Summary

• The JSON holds only field group settings, not the values entered for each post
• For a one-time move, use "Export As JSON" and "Import JSON" under ACF "Tools." Groups with the same key are overwritten, so back up the destination first
• For ongoing syncing, use Local JSON by creating an acf-json folder in your theme, and apply changes from the sync tab in the list
• When you change the save location, use acf/settings/save_json and acf/settings/load_json as a pair
• ACF 6.8 and later support wp acf json status / sync / export / import in WP-CLI

Related articles:

• How to use ACF (Advanced Custom Fields)
• What to do when ACF fields don't save
• How to create a WordPress child theme

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)