Cloudflare R2
Cloudflare R2 is S3-compatible object storage with no fees for data leaving the bucket (egress). WP Media Cloud uploads your Media Library to an R2 bucket and serves every file from your bucket’s public address, ideally a custom domain on Cloudflare’s network.
Setup takes about 10 minutes. You need WP Media Cloud 1.1.7 or newer to connect with a token limited to a single bucket, which is what this guide uses.
How R2 access works#
Cloudflare uses two kinds of access, and WP Media Cloud asks for them in two separate parts of the setup wizard. Only the first is required.
| 1. Bucket access | 2. Bucket list and storage stats | |
|---|---|---|
| Required? | Yes | No, optional |
| What you create | An R2 API token with Object Read & Write, limited to your one bucket | A Cloudflare API token with only Workers R2 Storage: Read |
| What you paste into the plugin | Access Key ID and Secret Access Key | The token value |
| What it lets the plugin do | Upload, serve, restore and delete files in that one bucket | Show your bucket list in the wizard, and storage size and file count on the Dashboard |
| What it cannot do | Touch any other bucket or anything else on your account | Change or delete anything. It can only read bucket names and usage. |
Why two? Cloudflare only lets tokens that can see the whole account list buckets or report storage totals. A token limited to one bucket cannot do either, however it is set up. So instead of giving the plugin write access to every bucket, you give it write access to one bucket, and optionally read-only access for the list and the stats.
If you skip the optional part, everything works the same. You type the bucket name instead of picking it from a list, and the Dashboard’s R2 storage card shows a short note instead of numbers.
Before you start#
- A Cloudflare account with R2 enabled. Cloudflare asks for a payment method before you can use R2, even if you stay within the free allowance.
- A domain on Cloudflare (recommended). To serve files from your own address, such as
media.example.com, the domain must be in the same Cloudflare account as the bucket. Without one, you can use the freer2.devaddress for testing. - WP Media Cloud 1.1.7 or newer. Older versions need an account-wide Admin token for the setup wizard.
- On multisite: subsites can share one bucket when each uses the path prefix
sites/%site_id%, or each can have its own bucket (see the FAQ).
Step 1: Create a bucket#
- In the Cloudflare dashboard, open R2 object storage.
- Select Create bucket.
- Enter a name. Bucket names use 3 to 63 lowercase letters, numbers and hyphens, for example
example-media. - Leave Location on Automatic, or pick the region closest to most of your visitors.
- Leave the jurisdiction on the default setting. WP Media Cloud does not support EU or FedRAMP jurisdiction buckets yet.
- Select Create bucket.
Step 2: Make the bucket public#
New buckets are private, so visitors cannot load your images until you give the bucket a public address. Choose one of the two options below.
Option A: Custom domain (recommended)#
- Open your bucket and select Settings.
- Under Custom Domains, select Add.
- Enter a subdomain such as
media.example.comand select Continue. - Review the DNS record and select Connect Domain.
- Wait until the domain shows as Active. This usually takes a minute or two.
Files served from a custom domain are cached on Cloudflare’s network. WP Media Cloud stores every file with a one-year cache header, so repeat visits load from the edge. When a file is re-uploaded under the same name, for example after an image optimizer compresses it, Cloudflare and browsers may keep the earlier copy. Purge that file from the Cloudflare cache. Images, video, PDFs, CSS and JavaScript are cached by default, and no extra cache rules are needed.
Option B: r2.dev address (testing only)#
- Open your bucket and select Settings.
- Under Public Development URL, select Enable.
- Type
allowand select Allow. - Copy the address shown, which looks like
https://pub-xxxxxxxx.r2.dev.
Do not use r2.dev on a live site. Cloudflare rate-limits r2.dev addresses, does not cache them, and describes them as for development only. Busy pages start failing with 429 Too Many Requests. Switch to a custom domain before launch.
Step 3: Create the bucket token (required)#
This token gives WP Media Cloud access to your one bucket and nothing else.
- Go to R2 object storage and open the Overview page.
- Under Account Details, select Manage next to API Tokens.
- Select Create Account API token.
- Give it a name you will recognise, such as
WP Media Cloud - example.com. - Under Permissions, choose Object Read & Write.
- Under the bucket scope, choose Apply to specific buckets only and select your bucket.
- Leave TTL on Forever. If the token expires, your site stops offloading new uploads.
- Select Create Account API token.
- Copy the Access Key ID and the Secret Access Key into a password manager.
Copy the Secret Access Key now. Cloudflare shows it only once. If you lose it, create a new token. The same page also shows a token value and an S3 endpoint; you do not need either for this step.
Step 4: Find your Account ID#
On the R2 object storage Overview page, the Account ID is listed under Account Details. It is 32 letters and numbers. You can also find it on your account’s home page in the Cloudflare dashboard.
Step 5: Connect WP Media Cloud#

In WordPress, open Media Cloud in the admin menu. The setup wizard opens on first use. Choose Cloudflare R2 and select Continue.
To change your bucket or keys later (WP Media Cloud 1.1.7.1 and newer), go to Settings and select run the setup wizard next to your provider. The wizard opens with your current values filled in. Saved keys show as Saved, so you only paste the ones you are changing. Your offloaded files, records and other settings are kept.
Part 1: Bucket access (required)#
| Field | What to enter |
|---|---|
| Account ID | From Step 4 |
| Bucket name | Exactly as shown in R2, for example example-media |
| Access Key ID | From Step 3 |
| Secret Access Key | From Step 3 |
| CDN URL | Your public address from Step 2, for example https://media.example.com. Use your custom domain or r2.dev address, never the r2.cloudflarestorage.com endpoint. |
Select Test connection. WP Media Cloud uploads a tiny test file to your bucket and deletes it again. When you see Connected. Uploading and deleting in “your-bucket” both work., part 1 is done. If you see an error, check Troubleshooting below. After you finish the wizard, you can also open Health and select Run All Checks: the Upload Test check uploads and deletes a test file, and should say Test file uploaded and deleted successfully.
Part 2: Bucket list and storage stats (optional)#
Skip this part to keep WP Media Cloud limited to one bucket. Fill it in to see your bucket list in the wizard, and your R2 storage size and file count on the Dashboard.
First, create a read-only token in Cloudflare:
- In the Cloudflare dashboard, open My Profile and go to API Tokens.
- Select Create Token, then Create Custom Token at the bottom of the page.
- Name it, for example
WP Media Cloud - read only. - Under Permissions, choose Account, then Workers R2 Storage, then Read. Add nothing else.
- Under Account Resources, choose Include and your account.
- Select Continue to summary, then Create Token.
- Copy the token. Cloudflare shows it only once.
Then, in the wizard:
- Leave Auth Method on API Token and paste the token.
- Select Load buckets. You can pick your bucket from the list to fill in the bucket name in part 1.
- Select Continue to finish.
Email + Global Key also works, but your Global API Key gives full control of your entire Cloudflare account. A read-only token is much safer.
Alternative: Connect with wp-config.php#

Instead of the wizard, you can define your settings in wp-config.php, above the line /* That's all, stop editing! */. Values set here override anything saved in the admin, which suits sites managed in version control.
define( 'WPMC_PROVIDER', 'r2' );
define( 'WPMC_R2_ACCOUNT_ID', 'your-account-id' );
define( 'WPMC_R2_ACCESS_KEY_ID', 'your-access-key-id' );
define( 'WPMC_R2_SECRET_ACCESS_KEY', 'your-secret-access-key' );
define( 'WPMC_R2_BUCKET', 'your-bucket-name' );
define( 'WPMC_R2_CDN_URL', 'https://media.example.com' );
// Optional (1.1.7.1 and newer): read-only token for the bucket list and storage stats.
define( 'WPMC_R2_API_TOKEN', 'your-read-only-token' ); The first six lines are required. The last line is optional and matches part 2 of the wizard.
Multisite: constants in wp-config.php apply to every subsite, so they point every subsite at the same bucket. That works when each subsite keeps its files in its own folder: also add define( 'WPMC_PATH_PREFIX', 'sites/%site_id%' );. Or set up each subsite in its own dashboard. See Custom path prefix.
After setup#

- New uploads go to R2 automatically and are served from your CDN URL.
- Existing media is not moved until you start a bulk offload from the Dashboard. On large libraries,
wp wpmc offloadis faster; on multisite,wp wpmc offload --networkcovers every subsite. - Changing your public address later, for example from r2.dev to a custom domain: update the CDN URL in Settings, then select Update all media URLs so existing offloaded items use the new address.
- WooCommerce downloadable products stored in R2 are delivered with short-lived signed links, using the bucket keys from part 1. No extra Cloudflare setup is needed.
- Dashboard stats: with the optional read-only token, the Dashboard shows R2 storage size and file count. Cloudflare does not report bandwidth for R2, so bandwidth shows as N/A.
Already using an Admin token?#
Sites set up before 1.1.7 used an Admin Read & Write token, which can create and delete every bucket on the account. It keeps working, and you do not have to change anything. To tighten access:
- Create a bucket token as in Step 3.
- Optionally create a read-only token as in part 2.
- In Settings, select run the setup wizard. Paste the new Access Key ID and Secret Access Key (and the read-only token, if you made one), select Test connection, and finish.
- Once everything works, delete the old Admin token in Cloudflare.
Your offloaded files stay where they are. Only the credentials change.
Troubleshooting#
| What you see | What it means | How to fix it |
|---|---|---|
| Load buckets says Cloudflare refused the bucket list | The token in part 2 cannot list buckets. This always happens with the bucket token from Step 3, because single-bucket tokens cannot list buckets. | Type the bucket name in part 1, or create the read-only token from part 2. |
| Load buckets is greyed out | No token has been added in part 2. | Expected if you are skipping part 2. Type the bucket name in part 1. |
Test connection: SignatureDoesNotMatch | The Access Key ID or Secret Access Key is wrong. | Paste both again, with no spaces at either end. If you are unsure of the secret, create a new token. |
Test connection: AccessDenied or 403 | The token is not allowed to write to this bucket. | Check the token has Object Read & Write (not Object Read only) and that your bucket is selected in its bucket scope. |
Test connection: NoSuchBucket or 404 | The bucket name or Account ID does not match. | Copy the bucket name exactly from R2 and check the Account ID. EU and FedRAMP jurisdiction buckets are not supported yet. |
| Test connection: “The Account ID should be 32 letters and numbers” | Something other than the Account ID was pasted, often the token or the endpoint URL. | Copy the Account ID from Step 4. |
| Images are broken, or a file URL shows 401, 403 or 404 | The bucket is not public, or the CDN URL is wrong. | Complete Step 2, then check the CDN URL opens a file in your browser. It must be your custom domain or r2.dev address, not the r2.cloudflarestorage.com endpoint. |
429 Too Many Requests on images | You are serving from r2.dev, which Cloudflare rate-limits. | Connect a custom domain (Step 2, option A), update the CDN URL, then select Update all media URLs in Settings. |
| New uploads stay on your server | Offload on upload is switched off. Before 1.1.7.1, finishing the setup wizard could switch it off. | In Settings, turn on Offload on upload and Rewrite URLs, then save. Use bulk offload for anything uploaded in the meantime. |
| Dashboard says R2 storage totals are not available | No read-only token has been added, or it lacks the right permission. | Optional. Add a token with Workers R2 Storage: Read (part 2). Offloading and serving are not affected. |
| Browser console shows CORS errors | A script is fetched from the bucket’s domain, or a font while Serve fonts from your site is off. Fonts load from your site by default and need no CORS. Ordinary images and video do not need CORS. | On the Health tab, run the Web Fonts (CORS) check and click Allow this site to add the rule to the bucket. If the button is not shown, your access key cannot change the bucket’s CORS rules: in the bucket’s Settings, add a CORS policy that allows GET from your site’s address. |
FAQ#
Is a token limited to one bucket really enough? Yes. It covers everything WP Media Cloud does with your files: uploading, serving, restoring and deleting. The optional read-only token adds only the bucket list and the storage numbers.
Do I need both tokens? No. The bucket token is required. The read-only token is optional.
Can the read-only token change anything? No. Workers R2 Storage: Read can list bucket names and read usage figures. It cannot create, change or delete buckets or files. It can see the names of every bucket on your account, so skip it if you would rather the plugin not see other buckets.
Can I use one bucket for several sites? Yes, when each site has its own path prefix. WP Media Cloud stores files by upload date and file name, such as 2026/10/photo.jpg, so two sites without a prefix can overwrite each other’s files. On a multisite network, set Path prefix to sites/%site_id%. For separate sites, give each one a prefix of its own, such as shop and blog. A staging site should still use its own bucket. See Custom path prefix.
Does R2 support object permissions (ACLs)? No. Whether files are public is set on the bucket in Step 2, not per file. WP Media Cloud never sends ACL headers to R2.