Migration & Backup

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.

Varun DubeyVarun Dubey
·13 min read
Diagram of wp-content moving from /var/www/html to /var/www/shared/content with plugins, themes and uploads, plus WP_CONTENT_URL

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

WP_CONTENT_DIR

Filesystem path of the content directory

ABSPATH . 'wp-content'

Full path, no trailing slash. Defined early, before the database loads.

WP_CONTENT_URL

URL of the content directory

get_option( 'siteurl' ) . '/wp-content'

Full URL, no trailing slash. Defined after the database loads, so it can read the site URL.

WP_PLUGIN_DIR

Filesystem path of plugins

WP_CONTENT_DIR . '/plugins'

Follows WP_CONTENT_DIR unless you set it.

WP_PLUGIN_URL

URL of plugins

WP_CONTENT_URL . '/plugins'

Follows WP_CONTENT_URL unless you set it.

PLUGINDIR

Old relative plugin path kept for backward compatibility

'wp-content/plugins'

Relative to ABSPATH. The wp-config.php docs suggest setting it only if a plugin has compatibility trouble.

WPMU_PLUGIN_DIR / WPMU_PLUGIN_URL

Must-use plugins

WP_CONTENT_DIR . '/mu-plugins' and WP_CONTENT_URL . '/mu-plugins'

Move with the content directory.

UPLOADS

Uploads folder, relative to ABSPATH

not defined

Overrides the upload_path and upload_url_path options. URL is built from the site URL, not WP_CONTENT_URL.

upload_path option

Uploads folder, absolute or relative to ABSPATH

'' (empty means WP_CONTENT_DIR/uploads)

Hidden in Settings, Media unless it already holds a non-default value.

upload_url_path option

Base URL of the uploads folder

Empty (derived)

The partner of upload_path. Set both or neither.

WP_LANG_DIR

Translation files

WP_CONTENT_DIR . '/languages' if that folder exists

Core also falls back to wp-includes/languages.

Three consequences follow from that table.

  1. Every _DIR constant needs its _URL partner. Change WP_CONTENT_DIR and leave WP_CONTENT_URL alone and WordPress will write files to the new place while building links to the old one.
  2. Moving WP_CONTENT_DIR moves plugins, must-use plugins, themes, languages and the uploads folder with it, because each defaults to a path under it. You only add WP_PLUGIN_DIR when plugins must live somewhere else.
  3. UPLOADS is 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_DIR

Always 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.

  1. Back up the database and the files. A restore is the only real undo.
  2. Put the site in maintenance mode so nobody uploads a file halfway through the copy.
  3. Copy, do not move, the folder to the new location. Keep the original until the site is verified.
  4. Fix ownership and permissions on the new location so the web server user can write to it.
  5. Make the new path reachable by URL in the web server, if it is outside the web root.
  6. Add the constants to wp-config.php.
  7. Flush caches: object cache, page cache and PHP opcache.
  8. 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 UPLOADS is defined, core sets the directory to ABSPATH . UPLOADS and the URL to the site URL plus UPLOADS. It does not look at WP_CONTENT_DIR or WP_CONTENT_URL at all.
  • It overrides the upload_path and upload_url_path options. 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/uploads

Two 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_path

Use 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 so plugin_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 PLUGINDIR as 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-run runs the whole operation and shows the report without saving anything.
  • --skip-columns=guid leaves the GUID column alone. GUIDs are identifiers, not links.
  • --all-tables-with-prefix covers tables your plugins registered outside $wpdb; --all-tables covers the whole database and overrides the other flags.
  • --network runs across every site table on multisite.
  • --export=file.sql writes the changes to an SQL file instead of changing the database.
  • --precise forces 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 after UPLOADS or upload_path is applied, so your base path still counts.
  • Older networks that still use ms-files rewriting follow a different path. UPLOADBLOGSDIR defaults to wp-content/blogs.dir, BLOGUPLOADDIR is an absolute path, and the URL becomes /files. In that mode UPLOADS is honoured only for sites other than the main one and only when not switched to another site.
  • Search-replace needs --network, and often --url to target a single site.
  • upload_path is 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.

  1. Ask WordPress, not the filesystem. wp eval 'echo WP_CONTENT_DIR;' and wp eval 'echo WP_CONTENT_URL;' print what core actually loaded. The first form is the example in the WP-CLI docs.
  2. Inspect the upload array. wp eval 'print_r( wp_get_upload_dir() );' shows basedir, baseurl and error. A non-false error means core cannot write there.
  3. List what loaded. wp plugin list and wp theme list should show everything you expect. An empty list means core is looking in the wrong folder.
  4. Upload a file in the admin and confirm it lands on disk in the new folder and loads at the new URL.
  5. Install or update one plugin and confirm the files land in the new plugin folder.
  6. 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.
  7. Read the PHP error log for path warnings that did not show in the browser. If WP_DEBUG_LOG is 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 flush

Restart 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.

Part of the Wbcom Designs family

The all-in-one WordPress community stack

Also ours: wbcomdesigns.comvapvarun.combrndle.com