Decide to migrate wordpress media to s3 and you discover quickly that the first attempt rarely finishes. SSH disconnects. Process killed. Disk runs out. A safe migration plan is what separates a clean cutover from a week of broken images. This is that plan.
Start with an inventory
Count your attachments. Note total size. Check disk free on the origin. If your library is bigger than your spare disk, do not even consider running operations that copy locally first. Stream straight to S3.
A simple WP-CLI command can produce the count and total size in one go. Save the numbers, you will use them to estimate the migration window.
Order matters
Migrate the original files first. Then the resized variants. Then any srcset variants generated by your theme. Doing originals first means a partial migration still serves usable images, even if the small variants have not arrived yet.
Most plugins respect this order by default. Verify before you start.
Resumability is non negotiable
A migration of ten thousand images takes hours. Your SSH session will drop. Your terminal will crash. The migration must be able to resume from where it stopped without restarting from zero. Defyn Media Offload ships a WP-CLI command that uses cursor based resumption to handle exactly this.
Run the command under nohup or tmux so the process survives the SSH disconnect. With the Defyn Media Offload plugin you can also reconnect and re run the same command; it picks up where the cursor left off.
Verify before you cut over
After migration runs, sample a hundred random attachments and confirm each one resolves from the CDN. Run the plugin verification command to scan for object keys that should exist but do not.
Do not flip the rewrite filter on until verification passes. Premature cutover gives readers broken images.
The cutover
Enable URL rewriting in the plugin. Spot check a handful of pages, including a heavy gallery page and a WooCommerce product. Watch the network panel for any image still served from the origin.
Once everything is rewritten and serving correctly, the migration is done. The local files can be removed in a separate optional pass.
Frequently asked questions
How long does it take to migrate wordpress media to s3?
A library of ten thousand attachments typically migrates in two to four hours on a decent connection. Bigger libraries scale linearly.
Can I migrate while the site is live?
Yes. New uploads land in S3 from the moment you enable the plugin. The migration handles existing media in the background.
What if the migration fails halfway?
A resumable command picks up at the cursor. The right plugin treats interruption as normal, not an error.
Do I delete local files after?
Optional. Many teams keep them as a belt and braces backup for the first month, then delete to reclaim disk.
Related reading
- Offload media without breaking URLs
- Amazon S3 setup guide
- Defyn Media Offload on WordPress.org – the plugin behind these techniques.
