Custom path prefix
A path prefix puts your offloaded files in a folder inside the bucket, for example media/2026/10/photo.jpg instead of 2026/10/photo.jpg. Use it to keep several sites apart in one bucket, or to keep media separate from other files.
Bucket paths without a prefix#
By default a file’s key in the bucket is its path inside your uploads folder:
| File on your server | Key in the bucket |
|---|---|
wp-content/uploads/2026/10/photo.jpg | 2026/10/photo.jpg |
wp-content/uploads/sites/3/2026/10/photo.jpg (multisite subsite) | 2026/10/photo.jpg |
wp-content/uploads/photo.jpg (month and year folders off) | photo.jpg |
The file’s address is your CDN URL (or the bucket’s address with Direct Bucket) followed by the key.
On multisite, subsites without a prefix all write to the same keys. Two sites that upload photo.jpg in the same month would overwrite each other, which is why sites sharing a bucket need a prefix.
Setting a path prefix#

- Go to Media Cloud > Settings and find the Offload Behaviour card.
- Enter your prefix in the Path prefix field, for example
media. Leading and trailing slashes are removed. - Click Save Settings.
The prefix can also be set in wp-config.php, which takes priority over the field:
define( 'WPMC_PATH_PREFIX', 'media' ); On multisite, a constant applies to every subsite, so use a token (below) to keep sites apart.
Tokens#
| Token | Becomes | Example prefix | Example key |
|---|---|---|---|
%site_id% | The site’s ID on multisite (1 on a single site) | sites/%site_id% | sites/3/2026/10/photo.jpg |
%folder% | The file’s folder in FileBird, Real Media Library or HappyFiles, in lowercase with hyphens; nothing for files outside a folder | media/%folder% | media/products/hero-shots/2026/10/photo.jpg |
Tokens are read when a file is offloaded. Moving a file to another folder later does not move it in the bucket, and its URLs keep working. See Media folder plugins.
When to use a path prefix#
- Multiple sites sharing one bucket: on multisite, set the prefix to
sites/%site_id%on every site, so each site’s files stay apart. Clean Up Deleted Media and Recover Records from Bucket refuse to run while sites share a bucket without a prefix, since a file could belong to any of them. A main site without a prefix next to subsites usingsites/%site_id%is fine. - A bucket used for other files too: a prefix such as
mediakeeps WordPress files in one folder. - Media folders:
media/%folder%mirrors your FileBird, Real Media Library or HappyFiles folders in the bucket.
A staging site should still use its own bucket rather than a prefix in the production bucket, so deleting media on staging can never touch production files.
Changing the prefix on an existing site#
New uploads use the new prefix right away. Files already offloaded stay at their original bucket path, and their records keep pointing there, so both old and new files keep working. You do not need to move anything.
To move existing files under the new prefix anyway:
- Copy the files from the old path to the new path with your storage provider’s dashboard or CLI tools.
- In Media Cloud > Settings, click Reset All Settings, tick Also forget all offload records and click Reset settings and records. The Setup Wizard opens: connect the same bucket again, then enter the new prefix in Path prefix and save. Nothing is deleted from the bucket.
- Run Recover Records from Bucket. It finds the files under the new prefix and recreates the records.
- Check a few images, then delete the files at the old path.
Files imported from other plugins#
Files imported from WP Offload Media, Advanced Media Offloader or Media Cloud by ILAB keep the keys those plugins used, which may start with a prefix such as wp-content/uploads/. WP Media Cloud serves them from those exact keys, in the Media Library, in srcset and in post content. New uploads use your own prefix setting.
When you move from WP Offload Media with the setup wizard, Use these settings fills in its object prefix, wp-content/uploads by default, so new uploads land next to the imported files. Change or clear the prefix in Settings if you want new uploads elsewhere.