Block Migrator
A WordPress plugin for exporting and importing Gutenberg block content between WordPress sites — with all block structure, settings, and text preserved exactly as built.
by SquareBow · github.com/squarebow/block-migrator · website
Install
No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:
wp plugin install https://github.com/squarebow/block-migrator/archive/refs/heads/main.zipExport and import Gutenberg block content between WordPress sites — structure, settings, and text all preserved exactly as built. No broken layouts. No manual fixes.
Table of Contents
- Why this plugin exists
- Before you start
- How it compares
- What is exported
- Installation
- How to export
- How to import
- Images and media
- Patterns and reusable blocks
- Custom post types
- Plugin requirements scanner
- Frequently asked questions
- Contributing
Why this plugin exists
If you have moved a WordPress site and watched carefully built block layouts collapse into broken or unrecognised mess, you know the problem.
Most migration tools do not understand Gutenberg block markup. They either flatten content to plain HTML — stripping every layout setting in the process — or they move the raw database content but break synced patterns, corrupt block attributes, or leave you with "Unknown Block" errors throughout.
The result is always the same: hours of manual work clicking into every page and post, rebuilding layouts block by block, converting WP generic blocks to something more advanced. On a real content-heavy site that can mean thousands of individual operations.
Block Migrator eliminates all of that. It exports content exactly as it sits in the database and imports it unchanged on the destination - without touching the database in the process.
Open the post in the editor and it looks identical to the source.
Before you start
The single most important step in any migration is matching your block plugins between sites. Do this before exporting anything.
Block content is stored as raw markup that only makes sense when the plugin that created it is installed and active. If the destination site is missing a block plugin, those blocks will appear broken — regardless of which migration tool you use.
Before you export:
- Check which block plugins are active on the source site (from where you are exporting)
- Install and activate the same plugins on the destination site (to where you are importing)
- Same goes for CPT plugins if you select CPTs on the Export tab
- The theme does not need to match — only the plugins
Block Migrator helps with this: the moment you select an export file on the import tab, it automatically scans the content and shows you exactly which plugins are needed, their status on the current site, and links to install anything missing.
How it compares
| WordPress XML export | Block Migrator | |
|---|---|---|
| Preserves block markup | Partially — can corrupt | Yes — exactly as built |
| Remaps synced pattern IDs | No — breaks silently | Yes — automatically |
| Warns about missing block plugins | No | Yes — before import |
| Selective post/page export | No — all or nothing | Yes — per post |
| Image sideloading | No | Yes — optional, batched |
| Works across different themes | Yes | Yes |
| Export patterns and posts together | No | Yes |
| Per-post conflict resolution | No | Yes |
What is exported
Included in every export:
- All block content and markup with every setting and attribute
- Post title, slug, status, excerpt, and menu order
- Categories and tags — created on the destination if they don't exist
- Featured image URL and alt text
- Block plugin post meta
- SEO meta (Yoast SEO, Rank Math, All in One SEO)
- Page template setting
- Synced and unsynced patterns with automatic ref ID remapping
- Any public custom post type registered on the source site
Not included:
- Media files themselves — image URLs inside content are preserved and images will still display, loading from the source server (see Images and media)
- Theme and plugin global styles — global colour palettes, typography settings, and design tokens; set these up manually on the destination
- Navigation menus
- Users, comments, or site settings
- WooCommerce products or orders
Installation
From the WordPress admin:
- Go to Plugins → Add New → Upload Plugin
- Upload the plugin ZIP and click Install Now, then Activate
- Go to Tools → Block Migrator
Manual installation:
Upload the block-migrator folder to /wp-content/plugins/ and activate via Plugins → Installed Plugins.
How to export
- Go to Tools → Block Migrator → Export tab on the source site
- Select the post types you want, click Load Posts, and check the items to include
- Use the Published only toggle and the title search to narrow things down on large sites
- If your site uses patterns, click Load Patterns and select them — include patterns and posts in the same export file, not separate ones
- The plugin requirements panel shows automatically — review it to see what the destination site will need
- Click Download Export File
A .json file saves to your machine. This is everything Block Migrator needs to recreate your content on any destination site.
How to import
Make sure the required block plugins are installed and active on the destination site before importing. The scanner shows what is needed the moment you select the file.
- Go to Tools → Block Migrator → Import tab on the destination site
- Select the
.jsonfile — the plugin requirements panel appears immediately - Resolve any missing plugins shown before continuing
- Choose how to import posts:
| Option | When to use |
|---|---|
| Draft | Recommended — review layouts in the editor before publishing |
| Published | Go live immediately |
| Original | Keep the status the post had on the source site |
- Choose how to handle posts where a slug already exists:
| Option | What happens |
|---|---|
| Skip | Leave the existing post untouched |
| Overwrite | Replace its content and meta with the imported version |
| Create new | Import with a new unique slug, keeping both posts |
- Choose your image options (see Images and media)
- Click Import Content
After import, an expandable results screen shows exactly what was imported, updated, skipped, or failed. Import a few posts first to confirm layouts look right before doing a full site migration.
Images and media
If you don't download images
Image URLs inside your content are preserved exactly as exported. Images will still display on the destination site — they are just loading from the original source server. This is perfectly fine for development and staging workflows where the source site stays online.
It becomes a problem if the source site goes offline, changes domain, or if you are migrating to a permanent new home. Use the sideload options in the Import tab of the plugin to download the files to the destination.
Downloading featured images
When enabled, Block Migrator fetches each post's featured image from the source site and adds it to the destination media library. Already-downloaded images are deduplicated — re-running an import will never re-fetch a file already on the destination.
Downloading inline content images
When enabled, Block Migrator downloads all images inside post content that are hosted on the source site. It updates URLs in all the places block plugins store them: HTML attributes, block JSON settings, and inline CSS — all in a single pass.
Externally-hosted images (CDNs, stock photo services, third-party embeds) are left untouched.
Image download speed
Images are downloaded in batches after your posts are saved — not during the import itself. This means large image libraries will never cause a timeout. Choose the batch size that matches your hosting:
| Tier | Batch size | Best for |
|---|---|---|
| Safe | 10 images | Shared hosting, slow servers |
| Standard | 25 images | Most managed hosting — recommended default |
| Fast | 50 images | Dedicated or high-performance servers |
A real-time progress bar shows batch progress. If a batch fails you can retry just that batch without restarting.
The source site must be accessible while images download. If it is behind a password or VPN, skip sideloading and handle media separately.
Patterns and reusable blocks
Both synced and unsynced patterns (formerly Reusable Blocks) are fully supported.
Synced patterns store a database ID in post content — that ID is site-specific and completely different on the destination. Block Migrator handles this automatically: patterns are imported first, then every pattern reference inside post content is rewritten to the new ID before any post is saved.
Always include patterns and posts in the same export file. Export them separately and the remapping cannot happen — every synced pattern will appear broken on the destination. If you make a mistake just make a new export.
Custom post types
Any public custom post type registered on the source site appears automatically in the post type list on the Export tab. If a CPT does not exist on the destination, those posts are skipped with a clear message in the results — the import never fails silently.
The CPT slug must match exactly between sites. Make sure the plugin that registers the CPT is active on both sides before importing.
Plugin requirements scanner
Block Migrator checks plugin compatibility automatically every time you select an export file. No manual steps needed.
The scanner reads the file in the browser, identifies which plugins are needed, and checks their status on the current site before you click Import. It understands both free and premium versions of the same plugin — if the source used a premium variant and the destination has the free version (or vice versa), the scanner correctly shows those as compatible.
Results for each plugin:
| Status | What it means |
|---|---|
| 🟢 Active | Installed and active — ready to import |
| 🟢 Active (different version) | A free or premium variant is active — blocks will render correctly |
| 🟠 Installed, needs activation | On disk but not activated — go to Plugins and activate it |
| 🔴 Not active | Needs to be installed before importing |
| ⚠️ Unknown | Can't identify this plugin — install it manually before importing |
When unknown plugins are detected, a warning appears above the list. The import is not blocked, but you need to install those plugins first or content won't be properly imported.
Supported plugins, free & premium versions: Kadence Blocks, Stackable, GenerateBlocks, Greenshift, Spectra, Otter Blocks, CoBlocks, Ghost Kit, Ultimate Blocks, PostX, Rank Math SEO, Premium Blocks for Gutenberg, Getwid, Blocksy Companion, Advanced Gutenberg, all core WordPress blocks, and any plugin using standard Gutenberg block markup.
Frequently asked questions
Do both sites need the same block plugins? Yes — this is the most important prerequisite. Block markup is meaningless without the plugin that renders it. Install and activate the same block plugins on the destination before importing. Block Migrator tells you exactly what is needed.
Does the theme need to match? No. Block content is stored independently of the theme. You can switch themes between sites freely — only block plugins need to match.
My images aren't showing after import. What happened? If you did not use the sideload options on the Import tab, images are still loading from the source site. Check that the source site is accessible. If it has gone offline or changed domain, re-import with the inline image sideload option enabled to download the files to the destination.
I imported content without images. Can I download the images now without re-importing everything? Yes — re-import the same file with the image sideload options enabled on the import tab and set conflict handling to Overwrite. Posts will be updated with local image URLs and already-downloaded images are skipped automatically.
Will global styles, colour palettes, and typography settings carry over? No. These are stored in theme or plugin options, not in post content. Set them up manually on the destination. Content referencing a global colour will fall back to its raw value if the palette isn't recreated.
What happens when a post with the same slug already exists? You choose: Skip (leave it), Overwrite (replace with the imported version), or Create New (keep both, with a new slug on the incoming post).
Can I import the same file twice? Yes. Use Overwrite or Create New mode. Already-downloaded images are deduplicated and won't be re-fetched.
A plugin shows as "Unknown" — what should I do? Install and activate the plugin taged as "Unknown" on the origin site on the destination site as well before importing. Block Migrator shows the plugin name from the source site so you know what to look for. If you proceed without it, those specific blocks will show as "Unknown Block" in the editor until the plugin is activated — no data is lost.
Does it work on multisite? Yes, on individual sites within a multisite network. Network-active plugins are detected correctly.
Does it migrate WooCommerce products? No. Products involve complex relational data. Use WooCommerce's own import/export tools for those or a third-party tool.
Contributing
Block Migrator is open source. The repository lives at github.com/Squarebow/Block-Migrator.
Found a bug or have a suggestion? Open an issue — describe what you expected, what happened, your WordPress and PHP version, and the hosting environment. Screenshots and anonymised export file samples are always helpful for reproducing the problem.
Want to contribute code? Fork the repository, make your changes on a feature branch, and open a pull request. Keep PRs focused — one fix or feature per PR makes review much faster. For larger changes, open an issue first to discuss the approach.
Made with ❤️ in Slovenia