Docs

First-time setup

7 min readUpdated November 9, 2026

The setup wizard connects WP Media Cloud to your storage in three steps. If the site used another offload plugin, it can start from that plugin’s settings and import its records instead.

Before you start#

  • Install and activate the plugin (see Installation).
  • Create a bucket and access keys with your storage provider. Each provider guide shows where to find the values the wizard asks for: Bunny Edge Storage, Cloudflare R2, Amazon S3, Google Cloud Storage, DigitalOcean Spaces, Wasabi, Hetzner Object Storage, Backblaze B2 and S3-compatible endpoints.
  • Moving from WP Offload Media, Media Cloud or Advanced Media Offloader? You can skip this: the wizard reads that plugin’s bucket and keys (see Moving from another offload plugin, below).
  • You can activate your licence before or after setup.

Open the wizard#

Click Media Cloud in the WordPress admin menu. On a new site, the Setup Wizard opens automatically. It has three steps: Welcome, Configure and Done.

Moving from another offload plugin#

When the site has media offloaded by WP Offload Media, Media Cloud or Advanced Media Offloader, the wizard’s first screen shows it under Moving from another offload plugin?: the plugin, how many files it offloaded, the bucket and the provider. It is found even after that plugin was deactivated.

Setup wizard listing another offload plugin under Moving from another offload plugin
  1. Click Use these settings. The wizard picks the provider and fills in the bucket, region, endpoint, CDN address and access keys from that plugin’s settings or its wp-config.php constants.
  2. On Configure, check the fields. A box at the top says what was copied and lists anything still needed, for example HMAC keys for Google Cloud. Copied keys show as Copied from …: they stay on the server and are never sent to your browser. Paste a new value to replace one.
  3. Click Continue, then Save & import N files. WP Media Cloud saves the settings, then creates its own record for each offloaded file, with a progress bar. Nothing is uploaded again, moved or deleted.
  4. Follow the Next steps on the last screen: deactivate the old plugin if it is still active, check a few pages, then click Go to Dashboard.
Configure step with settings copied from the other plugin
Ready to save and import the files
Import finished with next steps

With WP Offload Media, new uploads go to the same folder in the bucket as before, such as wp-content/uploads/. On a multisite network, keys set as wp-config.php constants are only copied for a super admin. The details for each plugin are in Migrating from WP Offload Media, Migrating from Media Cloud by ILAB and Migrating from Advanced Media Offloader.

To set up from scratch instead, choose a provider card as below.

Step 1: Choose your storage provider#

  1. Click your provider’s card: Bunny.net, Cloudflare R2, Amazon S3, Google Cloud, DigitalOcean Spaces, Wasabi, Hetzner, Backblaze B2 or Custom S3. Use Custom S3 for MinIO, Ceph, Garage or other S3-compatible servers.
  2. Click Continue.
Setup wizard Choose your storage provider step

To keep credentials out of the database, click Configure via wp-config.php instead (below).

Step 2: Connect your provider#

The Connect screen shows only the fields your provider needs. Copy and paste each value rather than typing it.

Setup wizard Connect step for Bunny.net
  • Bunny.net: API Key, then Load Zones. Choose a Storage Zone, enter its Zone Password, then choose the Pull Zone (CDN).
  • Cloudflare R2: Account ID, Bucket name, Access Key ID, Secret Access Key, CDN URL. An optional read-only API Token enables the Load buckets button.
  • Amazon S3: Region, Access Key ID, Secret Access Key, Bucket name, and an optional CloudWatch Stats setting.
  • Google Cloud: HMAC Access Key, HMAC Secret, Bucket name, Location.
  • DigitalOcean Spaces, Wasabi, Hetzner: Region, Access Key, Secret Key, Bucket name.
  • Backblaze B2: Region (taken from the bucket endpoint, such as us-west-004), Key ID, Application Key, Bucket name.
  • Custom S3: Endpoint URL, Region, Access Key, Secret Key, Bucket, URL Style.

Bucket name#

Type the name exactly as your provider shows it. For most S3-type providers, a Load button beside the field lists your buckets; listing is optional. Keys restricted to one bucket often can’t list buckets: the wizard then shows the provider’s error under the field. Type the name and continue.

Test connection (Cloudflare R2 only)#

After entering keys and bucket, click Test connection. It uploads and deletes a small test file. Other providers have no test button here; check them on the Health tab after saving (Step 4).

Required for each provider#

Offloading only starts once the required values are filled in:

  • Bunny.net: storage zone, its password, and a pull zone.
  • Cloudflare R2: a CDN URL, either the r2.dev address or a custom domain on the bucket.
  • Other providers: region (where asked), keys and bucket. Custom S3 also needs the endpoint URL.

CDN Configuration#

This section appears for every provider except Bunny.net and Cloudflare R2. Choose one option:

  • Direct bucket URL: nothing to enter; files are served from the bucket address.
  • Custom CDN: enter a CDN URL.
  • Bunny.net CDN: enter the Bunny API Key, click Load Zones, then pick the Pull Zone. The CDN URL fills in automatically.
  • KeyCDN: enter the KeyCDN API Key, click Load Zones, then pick the Zone.
  • EWWW Easy IO: enter the EWWW API Key, click Load Sites, then pick the CDN Site.
  • CDN77: enter the CDN77 API Token, click Load Resources, then pick the CDN Resource.

You can change the CDN later on the Settings tab.

Step 3: Save#

  1. Click Continue to reach the All set! screen.
  2. Click Save & Go to Dashboard.

The wizard saves your provider settings and applies these default switches, found on the Settings tab:

  • Offload on upload: On
  • Rewrite URLs: On
  • Remove local files: Off
  • Delete from cloud when deleted in WP: Off

Versions before 1.1.7.1 could turn off Offload on upload and Rewrite URLs when the wizard finished. If you ran setup on an older version, check both on the Settings tab.

Step 4: Check that it works#

Health tab with Run All Checks
  1. Open the Health tab and click Run All Checks. It verifies that credentials are complete, pings your CDN address, and checks WP-Cron and loopback requests. The Upload Test check uploads and deletes a test file and should report success.
  2. Go to Media > Add New Media File and upload an image.
  3. Open Media > Library in list view. The image row should show In cloud.
  4. Open the image. The WP Media Cloud field should show Offloaded plus the remote path.
  5. Confirm that File URL starts with your CDN or bucket address.

If a row shows Offload failed, hover over it to read the reason, fix the cause, and click Retry. The provider guides list common errors.

Step 5: Offload your existing media#

Files uploaded before setup stay on your server and are served from there until moved. To move them:

  • Dashboard tab > Bulk Offload card > Offload All Media. It runs in the background.
  • Or run wp wpmc offload in WP-CLI, which is faster for large libraries.

If you imported records from another plugin, run Offload All Media too: it uploads anything that plugin had not offloaded and skips everything already imported.

Change your setup later#

  • Settings tab: change the CDN, object ACL and behaviour switches. Click Save Settings after any change.
  • To change the provider, bucket or keys, click run the setup wizard at the top of the Settings tab. It opens with your saved values.
  • Saved keys are masked. Paste a new value to replace one, or leave the field empty to keep the saved key.
  • Offloaded files and records are kept when you make these changes.
  • To import another plugin’s records into a site that is already set up, use the Migration tab.

Configure via wp-config.php#

Constants in wp-config.php keep credentials out of the database, backups and exports. A constant overrides the value saved in admin.

  1. On the wizard’s first step, click Configure via wp-config.php.
  2. Choose a Storage Provider. For providers other than Bunny.net and Cloudflare R2, also choose a CDN.
  3. Click Copy.
  4. Paste the code into wp-config.php above the /* That's all, stop editing! */ line.
  5. Replace each placeholder with your real values.
  6. Click Done, constants added.

The plugin looks for WPMC_PROVIDER, saves the provider and reloads the dashboard. If you see the WPMC_PROVIDER constant not found error, check the spelling and confirm the code sits above the stop-editing line.

WPMC_PROVIDERProvider
bunnyBunny.net
r2Cloudflare R2
awsAmazon S3
gcsGoogle Cloud Storage
doDigitalOcean Spaces
wasabiWasabi
hetznerHetzner Object Storage
b2Backblaze B2
s3Custom S3 (reads the WPMC_S3_* constants)
s3compatCustom S3-Compatible

Amazon S3 uses aws, not s3. Example for Cloudflare R2: set WPMC_PROVIDER to r2, then define WPMC_R2_ACCOUNT_ID, WPMC_R2_ACCESS_KEY_ID, WPMC_R2_SECRET_ACCESS_KEY, WPMC_R2_BUCKET and WPMC_R2_CDN_URL. The Health tab and Dashboard stats read these constants.

Multisite networks#

  • Run the wizard on each subsite from that subsite’s own Media Cloud menu. Each subsite keeps its own settings, queue and offload records.
  • Subsites can share one bucket when each uses its own path prefix: set Path prefix to sites/%site_id% on every subsite (see Custom path prefix). Without a prefix, files with the same upload date and name overwrite each other.
  • Constants in wp-config.php apply to every subsite, so don’t use them to set a single bucket without a per-site prefix.

Next steps#

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only