How to Move WordPress Content Directory (WP_CONTENT_DIR, UPLOADS, Plugin Paths)
How to move wp-content, plugins or uploads: WP_CONTENT_DIR and URL, why UPLOADS is relative, symlink vs upload_path, search-replace, multisite, and checks.

To move the WordPress content directory, set WP_CONTENT_DIR (full filesystem path) and WP_CONTENT_URL (full URL) in wp-config.php, copy the folder to the new place first, and make your web server serve that path at the URL you chose. Plugins and the uploads folder follow the content directory unless you give them their own setting. Themes cannot be moved on their own. The one setting people get wrong is UPLOADS: it is relative to the WordPress install folder, it cannot be an absolute path, and it ignores WP_CONTENT_URL.
We checked every constant and code path in this guide against the WordPress core source (default-constants.php, load.php, functions.php and theme.php on the WordPress/WordPress GitHub mirror, master branch) and against the developer.wordpress.org pages for Editing wp-config.php and WP-CLI, on 15 Nov 2026. WordPress 7.1 is the current release. If your site runs an older version, the core logic described here has been stable for many releases, but check your own wp-includes/functions.php if a behaviour looks different.
Most sites should leave the defaults alone. The people who do need this are the ones with a full disk, a locked-down host, a shared plugin folder across a server, or a deployment layout where code and content live in different places. If that is you, the sections below go in the order you would do the work.
Should you move the content directory at all?
Usually not. Moving folders is not a security measure: a site with an exploitable plugin is just as exploitable when its files sit under /content/ instead of /wp-content/, because attackers find paths from the HTML a page outputs. The honest reasons to do it are practical ones.
- The uploads have outgrown the main disk and you want them on a bigger volume.
- Your deployment tool replaces the code folder on every release, and uploads must survive between releases.
- Several sites on one server share the same plugin files.
- The host or a compliance rule fixes where writable files may live.
- You inherited a custom layout and need to understand or repair it.
If your reason is “hardening”, read our WordPress file permissions guide first. Correct permissions and keeping PHP from running in the uploads folder do more than a rename ever will.
What does each constant and option control?
Core builds all of these paths from a handful of constants. Knowing which one derives from which tells you what you must set together and what you can leave alone.
Setting | What it controls | Default (from core) | Notes |
|---|---|---|---|
| Filesystem path of the content directory |
| Full path, no trailing slash. Defined early, before the database loads. |
| URL of the content directory |
| Full URL, no trailing slash. Defined after the database loads, so it can read the site URL. |
| Filesystem path of plugins |
| Follows WP_CONTENT_DIR unless you set it. |
| URL of plugins |
| Follows WP_CONTENT_URL unless you set it. |
| Old relative plugin path kept for backward compatibility |
| Relative to ABSPATH. The wp-config.php docs suggest setting it only if a plugin has compatibility trouble. |
| Must-use plugins |
| Move with the content directory. |
| Uploads folder, relative to ABSPATH |
| Overrides the upload_path and upload_url_path options. URL is built from the site URL, not WP_CONTENT_URL. |
| Uploads folder, absolute or relative to ABSPATH |
| Hidden in Settings, Media unless it already holds a non-default value. |
| Base URL of the uploads folder | Empty (derived) | The partner of upload_path. Set both or neither. |
| Translation files |
| Core also falls back to wp-includes/languages. |
Three consequences follow from that table.
- Every
_DIRconstant needs its_URLpartner. ChangeWP_CONTENT_DIRand leaveWP_CONTENT_URLalone and WordPress will write files to the new place while building links to the old one. - Moving
WP_CONTENT_DIRmoves plugins, must-use plugins, themes, languages and the uploads folder with it, because each defaults to a path under it. You only addWP_PLUGIN_DIRwhen plugins must live somewhere else. UPLOADSis the odd one out and gets its own section below.
The same path logic also decides where several drop-ins are looked up. Core loads advanced-cache.php, object-cache.php, db.php, db-error.php and maintenance.php from WP_CONTENT_DIR, and writes debug.log there by default. Move the directory and your caching drop-ins and error pages must move with it. Our debug.log guide covers the log path in detail. The full list of related constants is in our 30 essential wp-config.php constants.
Where in wp-config.php do the constants go?
Above the line that reads /* That's all, stop editing! Happy publishing. */. Core reads WP_CONTENT_DIR very early in wp-settings.php, so a constant defined after that point is silently ignored and the default wins. WP-CLI follows the same rule: wp config set inserts new values before the “stop editing” anchor unless you pass --anchor and --placement.
There is one trap here. In the stock wp-config.php, ABSPATH is defined below the “stop editing” line. If you write ABSPATH . 'content' above it, the constant does not exist yet and PHP raises an error. Use __DIR__, which is the folder of wp-config.php itself, or a literal absolute path.
<?php
// Inside the web root, relative to wp-config.php.
// Use __DIR__, not ABSPATH: ABSPATH is only defined further down the file.
define( 'WP_CONTENT_DIR', __DIR__ . '/content' );
define( 'WP_CONTENT_URL', 'https://example.com/content' );Both of these can be set from the command line, which is less error-prone than hand editing:
# Checked on 15 Nov 2026 against the WP-CLI docs for wp config set
wp config set WP_CONTENT_DIR '/var/www/shared/content'
wp config set WP_CONTENT_URL 'https://example.com/content'
wp config get WP_CONTENT_DIRAlways run these only after the files have been copied (next section). Setting the constants first points WordPress at a folder that does not exist yet.
How do I move the whole wp-content folder?
Do it in this order. Each step has a reason, and swapping them is how sites end up with a white screen at midnight.
- Back up the database and the files. A restore is the only real undo.
- Put the site in maintenance mode so nobody uploads a file halfway through the copy.
- Copy, do not move, the folder to the new location. Keep the original until the site is verified.
- Fix ownership and permissions on the new location so the web server user can write to it.
- Make the new path reachable by URL in the web server, if it is outside the web root.
- Add the constants to wp-config.php.
- Flush caches: object cache, page cache and PHP opcache.
- Verify (see the checklist near the end), then retire the old folder.
# Checked on 15 Nov 2026. Paths and the www-data user are examples.
wp db export /root/backups/pre-move-$(date +%F).sql
tar -czf /root/backups/wp-content-$(date +%F).tar.gz -C /var/www/html wp-content
wp maintenance-mode activate
mkdir -p /var/www/shared
rsync -a /var/www/html/wp-content/ /var/www/shared/content/
chown -R www-data:www-data /var/www/shared/content
find /var/www/shared/content -type d -exec chmod 755 {} \;
find /var/www/shared/content -type f -exec chmod 644 {} \;Use rsync -a rather than mv when the target is on another disk: mv across filesystems is a copy followed by a delete, and an interrupted run leaves you with half the files in each place. The 755 and 644 modes are the common baseline, not a rule for your host; our WordPress file permissions guide explains when to use something tighter.
Make the URL work
If the new folder is under the web root, WP_CONTENT_URL is just the matching URL and nothing else is needed. If it is outside the web root, your web server has to map a URL to that folder. The config below is for Apache 2.4. We ran it through httpd -t on 15 Nov 2026 and it reported Syntax OK.
<?php
// wp-config.php: put these ABOVE the "That's all, stop editing!" line.
// Checked on 15 Nov 2026.
define( 'WP_CONTENT_DIR', '/var/www/shared/content' ); // Full path, no trailing slash.
define( 'WP_CONTENT_URL', 'https://example.com/content' ); // Full URL, no trailing slash.Alias /content/ /var/www/shared/content/
<Directory /var/www/shared/content/>
Options -Indexes
Require all granted
</Directory>
<Directory /var/www/shared/content/uploads/>
<FilesMatch "\.php$">
Require all denied
</FilesMatch>
</Directory>The second Directory block stops PHP files in uploads from being served. Do not apply that to the whole content alias without thinking: a few plugins expose PHP endpoints under their own folder, and those would return 403. Nginx needs the same two ideas, a prefix location with alias and a rule that denies PHP in uploads. We did not run the Nginx version here, so treat it as a starting point and test it with nginx -t:
location /content/ {
alias /var/www/shared/content/;
}
# Place this BEFORE your generic location ~ \.php$ block, so it wins.
location ~* ^/content/uploads/.*\.php$ {
return 403;
}Themes do not move on their own
The wp-config.php documentation says plainly that the themes folder cannot be moved, because core builds its path as WP_CONTENT_DIR . '/themes'. What you can do is register an extra theme directory with register_theme_directory(). Core guesses the URL for a root outside both ABSPATH and the content directory, and its own comment says the guess may be wrong, so correct it with the theme_root_uri filter. Put both in an mu-plugin.
<?php
/**
* mu-plugin: register an extra theme directory (does not replace wp-content/themes).
*/
register_theme_directory( '/var/www/shared/themes' );
// The URL for a root outside ABSPATH and WP_CONTENT_DIR is a guess; correct it here.
add_filter(
'theme_root_uri',
function ( $uri ) {
return str_starts_with( $uri, '/var/www/shared/themes' )
? 'https://example.com/shared-themes' . substr( $uri, strlen( '/var/www/shared/themes' ) )
: $uri;
}
);How do I move only the uploads folder?
You have three realistic options, and the UPLOADS constant is not the best of them. Here is why, straight from _wp_upload_dir() in core:
- When
UPLOADSis defined, core sets the directory toABSPATH . UPLOADSand the URL to the site URL plusUPLOADS. It does not look atWP_CONTENT_DIRorWP_CONTENT_URLat all. - It overrides the
upload_pathandupload_url_pathoptions. Only multisite networks that still use the old ms-files rewriting are an exception. - The wp-config.php docs state it directly: the path cannot be absolute and is always relative to ABSPATH. A Trac report asking WordPress to allow absolute paths dates from 2018 (see the mistakes box below).
So the constant can only point somewhere inside the WordPress install folder. For anything outside it, use one of these instead.
Option 1: a symlink (simplest, keeps every URL)
Copy the uploads to the new disk, then replace the folder with a symlink. WordPress still sees wp-content/uploads, so nothing in the database or in post content changes.
# Checked on 15 Nov 2026. /mnt/uploads is an example mount.
rsync -a /var/www/html/wp-content/uploads/ /mnt/uploads/
mv /var/www/html/wp-content/uploads /var/www/html/wp-content/uploads.old
ln -s /mnt/uploads /var/www/html/wp-content/uploads
chown -h www-data:www-data /var/www/html/wp-content/uploadsTwo honest caveats. Your web server must be allowed to follow symlinks (Apache needs Options FollowSymLinks or SymLinksIfOwnerMatch for that path; Nginx follows them by default). And some plugins check that their own folders sit under the content directory. A Contact Form 7 user on the Roots forum reported exactly this with a symlinked uploads folder (linked in the mistakes box below).
Option 2: upload_path and upload_url_path (absolute path outside the install)
Core’s code explains why this works. When upload_path is set, core joins it to ABSPATH with path_join(), which returns the value untouched if it is already absolute. The URL comes from upload_url_path if you set it. If you set an absolute upload_path and forget upload_url_path, core falls back to WP_CONTENT_URL . '/uploads', which is the wrong URL for a folder elsewhere. Set both.
# Checked on 15 Nov 2026. Serve /mnt/uploads at https://example.com/media/ in your web server first.
wp option update upload_path '/mnt/uploads'
wp option update upload_url_path 'https://example.com/media'
wp option get upload_pathUse a plain absolute path for upload_path. Existing media keeps working because the database stores each attachment’s file as a path relative to the uploads base folder (get_attached_file() prepends the base directory at read time). Copy the files and the library follows.
Option 3: the upload_dir filter (change only the URL)
Use this when files stay where they are but links must point at a CDN or a different host. The filter receives the array that wp_upload_dir() builds, with keys path, url, subdir, basedir, baseurl and error. We linted the snippet with php -l on PHP 8.5. Our WordPress CDN setup guide covers the other half of a CDN setup.
<?php
/**
* Serve upload URLs from a CDN host. Files still live in the normal uploads folder.
* Put this in an mu-plugin. Checked on 15 Nov 2026.
*/
add_filter(
'upload_dir',
function ( $uploads ) {
$uploads['baseurl'] = 'https://cdn.example.com/uploads';
$uploads['url'] = $uploads['baseurl'] . $uploads['subdir'];
return $uploads;
}
);Because the filter runs on every call, it also changes links in new uploads only. Old posts that stored the full old URL keep it until you rewrite them (next section).
Goal | Use | Changes the URL? | Main risk |
|---|---|---|---|
Uploads on a bigger disk, same URLs | Symlink | No | A plugin that insists on a real folder under the content directory |
Uploads outside the install, own URL | upload_path + upload_url_path | Yes | Forgetting upload_url_path; stored URLs in old content |
Files stay, links go to a CDN | upload_dir filter | Yes | Old content keeps the old URL until rewritten |
Everything under a new content folder | WP_CONTENT_DIR + WP_CONTENT_URL | Yes | Hardcoded paths in plugins and themes |
A folder inside the install, renamed | UPLOADS | Yes | Ignores WP_CONTENT_URL; overrides the options |
Can I move only the plugins folder?
Yes, with WP_PLUGIN_DIR and WP_PLUGIN_URL, and you must set both. Moving the plugins folder is the pattern for a server where several sites share one set of plugin files. Plugin activation is stored per site in its own database, so each site activates what it needs from the shared folder.
<?php
// Plugins only. Everything else stays in wp-content.
define( 'WP_PLUGIN_DIR', '/var/www/shared/plugins' );
define( 'WP_PLUGIN_URL', 'https://example.com/shared-plugins' );- An update run from one site changes the files for every site that shares the folder. Update during a quiet window and test each site afterwards.
- Core has a helper,
wp_register_plugin_realpath(), that exists soplugin_basename()can resolve symlinked plugin paths. That is one reason a symlinked plugin folder usually works, and also a hint that plugins which compute paths themselves can still trip over it. - If a plugin misbehaves after the move, the wp-config.php docs suggest also defining
PLUGINDIRas a compatibility setting.
Do not do this on a single site just to feel tidy. Shared plugin folders reward teams with a deploy process and punish everyone else.
Do I need wp search-replace after the move?
Only when the URL changes and the old URL is stored in the database. A pure filesystem move with identical URLs (the symlink case) needs no database change at all. Attachment records store a relative path, so they do not need touching either.
When the URL does change, post content, widgets, options and page-builder data may hold the full old address. WP-CLI handles serialized data correctly, which a plain SQL replace does not. These are the options that matter, taken from the WP-CLI search-replace guide and checked against the official command page on 15 Nov 2026:
--dry-runruns the whole operation and shows the report without saving anything.--skip-columns=guidleaves the GUID column alone. GUIDs are identifiers, not links.--all-tables-with-prefixcovers tables your plugins registered outside$wpdb;--all-tablescovers the whole database and overrides the other flags.--networkruns across every site table on multisite.--export=file.sqlwrites the changes to an SQL file instead of changing the database.--preciseforces PHP processing for every column, slower but safer on complex serialized data.
# Checked on 15 Nov 2026. Always dry-run first, with a fresh backup in hand.
wp db export /root/backups/pre-replace-$(date +%F).sql
wp search-replace 'https://example.com/wp-content/uploads' 'https://example.com/media' \
--skip-columns=guid --dry-run
# Looks right? Run it again without --dry-run.Replace the longest, most specific string you can. Replacing just the domain, or just “wp-content”, rewrites things you did not mean to touch.
What changes on multisite?
Constants like WP_CONTENT_DIR and WP_PLUGIN_DIR are set once for the whole network, so a move applies to every site. The uploads logic has extra rules, all visible in _wp_upload_dir():
- On a network created on WordPress 3.5 or later, every site except the main one gets
/sites/appended to the uploads base folder and URL. That happens afterUPLOADSorupload_pathis applied, so your base path still counts. - Older networks that still use ms-files rewriting follow a different path.
UPLOADBLOGSDIRdefaults towp-content/blogs.dir,BLOGUPLOADDIRis an absolute path, and the URL becomes/files. In that modeUPLOADSis honoured only for sites other than the main one and only when not switched to another site. - Search-replace needs
--network, and often--urlto target a single site. upload_pathis a per-site option on multisite, so moving the base with options means updating each site. A constant or a symlink applies to all of them at once.
How do I check the move worked?
Do these in order. Each one catches a different failure, and the first two take under a minute.
- Ask WordPress, not the filesystem.
wp eval 'echo WP_CONTENT_DIR;'andwp eval 'echo WP_CONTENT_URL;'print what core actually loaded. The first form is the example in the WP-CLI docs. - Inspect the upload array.
wp eval 'print_r( wp_get_upload_dir() );'showsbasedir,baseurlanderror. A non-falseerrormeans core cannot write there. - List what loaded.
wp plugin listandwp theme listshould show everything you expect. An empty list means core is looking in the wrong folder. - Upload a file in the admin and confirm it lands on disk in the new folder and loads at the new URL.
- Install or update one plugin and confirm the files land in the new plugin folder.
- Open the front end and the dashboard with the browser network tab open. Any 404 on a content URL is a hardcoded path or a missing web-server alias. A 403 or 500 is usually permissions or an overly strict deny rule.
- Read the PHP error log for path warnings that did not show in the browser. If
WP_DEBUG_LOGis on, the log is now in the new content folder, as our debug.log guide explains.
# Checked on 15 Nov 2026
wp eval 'echo WP_CONTENT_DIR . PHP_EOL . WP_CONTENT_URL . PHP_EOL;'
wp eval 'print_r( wp_get_upload_dir() );'
wp plugin list --fields=name,status
wp cache flushRestart PHP-FPM or reload opcache after the move as well. Opcache holds compiled files by path, and a stale entry for the old location is a classic reason a change “does nothing”. If you use Composer inside plugins or a custom layout, regenerate the autoloader so it does not hold old absolute paths.
Common mistakes people report
These come from forum threads and ticket discussions, paraphrased, with links. We checked the links on 15 Nov 2026. Several of the threads are old and a few never reached a fix, which we note where it applies.
- A plugin that hardcodes wp-content. Developers have complained about this since at least 2009 (
plugins_url()and the constants exist so nobody has to write the literal folder name), see Will Norris on hardcoding wp-content. A plugin author on WordPress.org told a user the plugin cannot detect a renamed content folder automatically and pointed to its filters; the user fixed it with custom filters, see the support thread (resolved). - Expecting UPLOADS to follow the content directory, or to accept an absolute path. A moderator on the WordPress.org forum confirmed it is intentional that UPLOADS is relative to ABSPATH and ignores WP_CONTENT_DIR, and called it a limitation, see this thread (closed, unresolved). A reporter who tried
define( 'UPLOADS', '/tmp' )got ABSPATH prepended to it, see Trac ticket 43047, mirrored on the wp-trac list. The ticket was marked new in that 2018 post; we could not confirm a later status. - Symlinking uploads and breaking a plugin that wants a real content folder. A user on a Bedrock-style layout with an atomic deployment found Contact Form 7 uploads not saving or attaching. The fix was a plugin-specific constant that set the temporary upload folder explicitly, see the Roots discussion (solved by the poster, May 2022). Check the plugin’s own documentation for a path setting before blaming WordPress.
- A blank screen after defining the constants. One poster added WP_CONTENT_DIR, WP_CONTENT_URL and WP_PLUGIN_URL and got a white screen with no explanation. The only reply was a link to a blog post, so the thread never explained the cause, see the thread. The cause in cases like this is almost always a wrong path or a folder the server cannot read. Turn on WP_DEBUG_LOG and read the real error.
- Directory “does not exist” errors on a local setup. After renaming content folders, a user on the Local community forum saw the admin work but theme uploads time out with errors about missing plugins and themes directories, and nobody posted a final fix, see the Local thread (2017). The lesson is to confirm the new folder really contains the plugins and themes subfolders, and that the web server user can read it, before touching anything else.
Frequently asked questions
Can WP_CONTENT_DIR be outside the web root?
Yes. WordPress only needs the filesystem path to read and write files. Browsers still need a URL, so the web server must map WP_CONTENT_URL to that folder with an alias or a symlink. Static files such as images, scripts and stylesheets are served from there; PHP files in plugins and themes are loaded by WordPress from disk and do not need to be web-reachable.
Is there a UPLOADS_URL constant?
No. We searched the core files for it on 15 Nov 2026 and found none. Use the upload_url_path option or the upload_dir filter.
Will moving wp-content break my media library?
Not by itself. Attachments store a path relative to the uploads base folder, and core prepends the base directory when it needs the file. Copy the files to the new base and the library finds them. It breaks when the files are missing at the new base, or when old posts hold the full old URL and the URL changed.
Which is better for a bigger disk, a symlink or upload_path?
A symlink if the URL should stay the same, since nothing in the database changes. upload_path with upload_url_path if you want WordPress itself to know the new location and serve the files from a separate URL.
Does moving the directory change how WordPress updates plugins?
Updates write to WP_PLUGIN_DIR, wherever that points. The permissions on the new folder decide whether updates succeed, which is why the ownership step comes before the constants in the order above.
The short version
Copy the content folder first, then set WP_CONTENT_DIR and WP_CONTENT_URL together above the “stop editing” line, using __DIR__ rather than ABSPATH. Add WP_PLUGIN_DIR and WP_PLUGIN_URL only when plugins need a separate home. Treat UPLOADS as an in-install, relative-path setting and reach for a symlink, the upload_path options or the upload_dir filter for anything else. Run wp search-replace only if the URL changed, with a dry run first. Verify with wp eval, an upload and a plugin install before you delete the old folder.
Plugins we build and run
We maintain these ourselves, which is why we can support them on your site.
- BuddyNextThe self-hosted community engine for WordPress
- BuddyXFree community theme, Pro when you outgrow it
- ReignPremium community theme. Add pieces, build anything
- JetonomyCommunity forum and Q&A for WordPress
- EventonomyEvents and RSVPs for WordPress communities
- LearnomyCourses and learning communities on WordPress
- ListoraDirectories and listings your members can browse
- SnipShareCode sharing built for developer communities
- WB Ad ManagerAd placements that turn traffic into revenue
- WP Career BoardA job board your community actually uses
- WP Sell ServicesSell services with offers, orders, and payouts
- MediaVersePhotos, video, and media albums for members
- WB GamificationPoints, badges, and rewards that keep members active
- Product RoadmapPublic roadmaps with voting your users trust



