Bulk Offload

New uploads are offloaded automatically. Bulk Offload is for the media that was already in your library before you set up OmniOffloader.

Open OmniOffloader → Offload. The page shows three numbers: Total Library Media, Already Offloaded and Local (Ready to Offload).

Start a bulk offload

1. Choose how much to offload:

   • All Local Media: every eligible attachment on your server.
   • Custom Amount: a set number. Pick a preset (5, 10, 25, 50, 100, 250, 500; only those below the number of eligible attachments are shown) or type any number.

2. Click Start Bulk Offload. The button shows how many attachments will run, for example Start Bulk Offload (25 of 1200).

3. Watch the progress bar and the activity log. Each attachment is listed as it finishes, and any errors are shown with the reason.

Try a small batch first

Start with Custom Amount → 10. Check that the images load correctly on your site, then offload the rest.

Can I close the tab?

Yes. The job runs in the background on your server and keeps going after you leave the page. You can come back at any time to see its progress.

Some hosts block WordPress’s internal “loopback” requests, which background jobs rely on. On those hosts, the open Offload page keeps the job moving instead. There, leave the page open until the run finishes, or use WP-CLI.

Cancel a run

Click Cancel at any time. The background worker stops right away. Attachments that were already offloaded stay offloaded. You can start again later, and the run continues with what is still local.

When things fail

A single broken attachment does not stop the run. It is logged, and the next attachment starts.

Files missing on this server

Sometimes WordPress lists an attachment whose file isn’t on the server, for example on a copy of the site that came without its uploads folder, or after files were deleted outside WordPress. There is nothing to upload, so OmniOffloader:

• skips it before uploading anything, and logs it as File missing on this server — skipped (not as a failure),
• marks it File missing in the Media Library,
• leaves it out of Local (Ready to Offload) and out of later runs, and says on the Offload page how many there are.

To offload them, put the files back in wp-content/uploads (same folders). The next Bulk Offload, or wp omnioffloader offload --all, finds them again by itself: it only checks the attachments marked missing, never the whole library.

After 10 failures in a row, OmniOffloader checks the connection to your storage provider:

• The provider answers: the failures belong to the attachments themselves. The run carries on, and the errors stay in the log. It only stops after 100 failures in a row.
• The provider does not answer: the run stops with status Stopped and shows the provider’s error, so you can fix the connection.

Attachments that failed before are moved to the end of the next run, so they never hold up a restart.

A file that your host’s time limit cuts short is reported and skipped, never retried forever.

Speed

How many files move at the same time is set by Transfer Speed. A faster setting finishes sooner on a server that can handle it.

Large libraries: use WP-CLI

Recommended for 5,000 items or more

If you have SSH access to your server, offload a big library with WP-CLI instead of this screen. On the Offload page, the Run this job from WP-CLI panel’s View command button opens the command in the WP-CLI reference on the Tools screen.

Why WP-CLI is the better choice for a big library:

• Faster. --concurrency uploads up to 64 files at once for that run. The admin screen stays at the Transfer Speed setting (at most 10).
• No browser needed. Nothing depends on an open tab or on WordPress’s background requests, which some hosts slow down or block.
• No web time limits. A web request is stopped after 30 to 60 seconds on most hosts. A terminal command is not.
• Easy to follow. A progress bar, or a log file you can check from anywhere, plus wp omnioffloader status with the speed and time left.
• Safe to stop and continue. Media that is already offloaded is skipped, so running the same command again picks up where it stopped.

1. See what would be offloaded. Nothing is uploaded:

   wp omnioffloader offload --all --dry-run

2. Try a small batch first, and check a few images on your site:

   wp omnioffloader offload --all --limit=500

3. Offload the rest in the background. It keeps running after you close the terminal and writes its progress to offload.log in your home folder. On a VPS or dedicated server, start with --concurrency=32; on shared hosting, leave it out:

   nohup wp omnioffloader offload --all --concurrency=32 > ~/offload.log 2>&1 &

4. Watch it with tail -f ~/offload.log (Ctrl+C only stops watching), or wp omnioffloader status for the speed and time left.

5. Stop it at any time with wp omnioffloader stop. Run the command from step 3 again to continue.

Fastest: a VPS or dedicated server, 64 files at once

With good bandwidth and many small files (thumbnails), run the same job in the background with 64 uploads at once:

nohup wp omnioffloader offload --all --concurrency=64 > ~/offload.log 2>&1 &

Start at 32 and move up to 64 if the server and your storage provider keep up. On shared hosting, leave --concurrency out. A large file still uploads at most 10 parts at once. To compare speeds before the big run, see Test the speed before a big run.

Run these from your WordPress folder, or add --path=<wordpress-folder>. For every option, see wp omnioffloader offload; for watching and timing a long run, see Long runs and log files.

No SSH access? This screen does the same job. It runs in the background on the server, so you can close the tab and come back.

One job at a time

Only one bulk job runs at a time: Bulk Offload, Bring Back, a retention update or a move to the current folder. This applies whether the job was started from these screens, the Media Library or WP-CLI. Two jobs never touch the same files. While a WP-CLI job runs, the Offload, Bring Back and Tools screens say so, with its progress, and their Start buttons wait until it finishes.

Single attachments

You can also offload one file at a time from the Media Library. Use the Offload now row action. See Media Library.