DEV Community

Aidan (Donghyuk) Lee
Aidan (Donghyuk) Lee

Posted on Fully Autonomous

I built a WordPress migration tool that checks its own work

#wordpress #python #opensource #webdev

Most WordPress migration tools end the same way: export finished. Finished is not the same as complete. Did every post make it? Every image? Does every old link still land somewhere?

What breaks when people leave WordPress

Before writing code, I collected 300 GitHub issues from four popular WordPress export tools and sorted them by title:

  • 27% were the tool itself crashing, timing out, or failing to install
  • 14% were about images
  • 12% were about URLs and permalinks
  • 10% were about HTML turning into broken Markdown

I also read 639 Hacker News comments from 21 threads about leaving WordPress. 111 of them describe a concrete difficulty. The most common were build and deploy work afterwards, losing comments, getting content out, and non-developers losing the ability to edit.

What wp-move does

  1. Reads posts, pages, media, categories and tags through the REST API. It only reads.
  2. Converts each post to Markdown with front matter. Anything Markdown can't hold (tables, embeds, forms) stays as HTML and is listed.
  3. Downloads images hosted on your site and rewrites their paths.
  4. Maps every old URL to its new path and writes _redirects and nginx files.
  5. Writes report.html and report.json, and exits with code 2 if posts, media, image references or internal links are missing. 
uvx --from git+https://github.com/AidanKR/wp-move@v0.0.1 wp-move pull https://your-site.example --out out
Enter fullscreen mode Exit fullscreen mode

Results on the demo site

On a local WordPress 7.1.3 with the official theme test data:

  • 144/144 posts and pages, including a draft and a scheduled post
  • 37/37 media originals
  • 0 pages under 95% of their words, 0 missing images, 0 broken internal links
  • 164/164 old URLs redirect to the new path through nginx (282/282 with --url-style slug)

Then I broke it on purpose: I deleted one image and one post from a copy. The report showed 143/144, 36/37, and 3 missing image references, and the command exited with code 2.

What it does not do yet

  • It has been tested only on the theme test data, not on real production sites.
  • _redirects has not been tested on Netlify or Cloudflare Pages yet.
  • No comment migration, no category or tag pages, no theme. Shortcodes are detected but not converted.

If you own a WordPress site, try it and open an issue with what the report got wrong (leave out anything private).

GitHub (MIT): https://github.com/AidanKR/wp-move
Demo video (6.5 min): https://youtu.be/-IhrdRSFLl8

Disclosure: this post was drafted by an AI agent (Claude) that also helped build the tool. Every number above comes from measured runs documented in the repository README.

Top comments (0)