Custom path prefix
The custom path prefix sets a folder path that WP Media Cloud prepends to every file it uploads to your cloud storage bucket. It controls how files are organised within the bucket and what the final URL looks like. Without a prefix, files are uploaded directly to the root of the bucket using WordPress’s default year/month folder structure.
How the path prefix works#
When WP Media Cloud uploads a file, it constructs the bucket path by combining your prefix with the file’s path relative to wp-content/uploads. For example, if WordPress stores a file at wp-content/uploads/2026/06/photo.jpg and your prefix is set to my-site, the file is uploaded to the bucket at my-site/2026/06/photo.jpg.
The full URL then becomes either:
https://[bucket-url]/my-site/2026/06/photo.jpgif no CDN is configuredhttps://[cdn-hostname]/my-site/2026/06/photo.jpgif a CDN is configured
The prefix is applied consistently to every file WP Media Cloud uploads, including all thumbnail sizes.
When to use a path prefix#
A path prefix is useful in several situations:
- Multiple sites sharing one bucket — use a different prefix per site (e.g.
site-oneandsite-two) to keep each site’s files in a separate folder within the same bucket. This avoids filename collisions and makes it clear which site a file belongs to. - Organising files by environment — use prefixes like
productionandstagingto separate media from different environments within the same bucket. - Matching an existing folder structure — if you are migrating from another plugin that used a specific path structure in the bucket, set your prefix to match so WP Media Cloud writes to the same location.
- Replicating wp-content/uploads structure — some setups use
wp-content/uploadsas the prefix to maintain the same path in the bucket as on the server, which makes it easier to compare local and cloud files.
Setting a path prefix#
Go to WP Media Cloud > Settings > Storage and enter your prefix in the Path Prefix field. Save settings.
Format guidelines:
- Do not include a leading or trailing slash. Use
my-sitenot/my-siteormy-site/. - Use only alphanumeric characters, hyphens, and forward slashes for nested folders. For example
sites/my-siteis valid. - Avoid spaces and special characters as they may cause URL encoding issues depending on your provider.
Changing the prefix on an existing site#
Changing the path prefix on a site that has already offloaded media requires care. New uploads will use the new prefix immediately. Files already offloaded will remain in the bucket at their original path and the old path will be in their attachment records.
This means after changing the prefix you will have two sets of URLs — old files pointing to the old path and new files pointing to the new path. Both will continue to work as long as the files exist at those paths in the bucket.
If you want to unify all files under the new prefix you need to:
- Move or copy existing files in the bucket from the old path to the new path using your storage provider’s dashboard or CLI tools.
Leaving the prefix empty#
If no prefix is set, WP Media Cloud uploads files directly to the bucket root using WordPress’s default year/month path. For example 2026/06/photo.jpg. This is a valid configuration and works well for single-site setups on a dedicated bucket.