How to move wp-content to a custom path with constants in WordPress

Contents

Introduction

This article is a comprehensive, step-by-step tutorial for moving the WordPress wp-content directory to a custom path by using constants. It covers reasons to move wp-content, required preparations, exact code snippets to add to wp-config.php, filesystem operations, webserver configurations for non-webroot locations, database updates, WP-CLI usage, multisite considerations, common pitfalls, testing and rollback procedures, permissions, and troubleshooting. All code examples are provided in runnable form and annotated so you can copy/paste safely.

Why move wp-content?

  • Organization: Use a different name or structure (for example, content instead of wp-content).
  • Security through obscurity: Reduces the chance of automated scanners assuming default paths (not a full security solution).
  • Split filesystem layout: Store uploads or plugins on a separate disk or mount point.
  • Serve assets from a different domain or subdomain: Easier to configure CDNs or separate virtual hosts if URLs are under your control.
  • Host-specific requirements: Some environments require custom paths or placing static assets outside the WordPress install.

High-level approaches

  1. Define WP_CONTENT_DIR and WP_CONTENT_URL (and optionally WP_PLUGIN_DIR/URL and WPMU_PLUGIN_DIR/URL) in wp-config.php. This instructs WordPress to load content from a custom path.
  2. Move or copy the actual files to the new filesystem location (or create a symlink from the old path to the new path).
  3. Update database entries (URLs and path references) where required, taking care with serialized data.
  4. Adjust webserver configuration if the content is placed outside the webroot (use Alias / location directives).
  5. Test and flush caches restore or rollback on failure.

Prerequisites and warnings

  • Backup everything: Database dump and a full filesystem backup.
  • Test on staging or local environment first.
  • Define constants early: If you set constants in wp-config.php, define them before WordPress is loaded (i.e., before require_once ABSPATH . wp-settings.php).
  • Plugin compatibility: Some plugins/themes hardcode wp-content paths they may break and need updates.
  • Multisite: Additional constants exist (WPMU_PLUGIN_DIR/URL), and uploads handling differs for subsites.
  • GUID caution: Do not blindly replace GUIDs in the DB unless you know the consequences.

Constants to use and what they do

  • WP_CONTENT_DIR — absolute filesystem path to the content directory.
  • WP_CONTENT_URL — public URL to the content directory (protocol host path).
  • WP_PLUGIN_DIR — absolute filesystem path to the plugins directory (if different from WP_CONTENT_DIR . /plugins).
  • WP_PLUGIN_URL — public URL to the plugins directory.
  • WPMU_PLUGIN_DIR / WPMU_PLUGIN_URL — same but for mu-plugins (must-use plugins).
  • UPLOADS — legacy constant controlling where uploads get placed can be used for relative custom upload location (careful with multisite and absolute paths).

Step-by-step: Move wp-content to a custom path (example: content)

1) Plan names locations

Example: you want to rename wp-content to content and place it inside the WordPress install (so web-accessible at https://example.com/content). Filesystem path might be /var/www/html/content.

2) Backup

  • Full filesystem archive (tar/zip).
  • MySQL dump: use mysqldump or WP-CLI db export.
# Filesystem backup (example)
tar -czf /root/backup-site-files-(date  %F).tar.gz /var/www/html

# Database backup (example)
mysqldump -u dbuser -p dbname > /root/db-backup-(date  %F).sql

# or using WP-CLI
wp db export /root/db-backup-(date  %F).sql

3) Copy or move files

Copy rather than move initially, so you can revert quickly if something goes wrong: 

# Using rsync to copy
rsync -av --progress /var/www/html/wp-content/ /var/www/html/content/

# Verify content copied, then you may remove the old folder when stable
# Keep the old folder for quick rollback (dont delete immediately)

4) Add constants to wp-config.php

Open wp-config.php and add the constants before the / Thats all, stop editing! Happy publishing. / or at least before the line that loads WP (require_once ABSPATH . wp-settings.php). Example: 




Notes:



    

  • Use the correct protocol (https://) in WP_CONTENT_URL to avoid mixed content warnings.
    • 

  • dirname(__FILE__) is commonly used to create reliable filesystem paths relative to wp-config.php.
    • 

  • Ensure these defines appear before require_once ABSPATH . wp-settings.php
    • 



5) Update uploads path (if needed)



WordPress normally keeps uploads under WP_CONTENT_DIR . /uploads. If you moved the entire content directory and the uploads directory is inside it then no further changes are necessary. If you want a different uploads location or URL, you can set the following options:



    

  • Option upload_path controls the filesystem path (legacy  relative behavior).
    • 

  • Option upload_url_path controls the URL for uploads (optional).
    • 



Example SQL to set these values (run in your database or using WP-CLI):


-- Set uploads path relative to ABSPATH (legacy approach)
UPDATE wp_options SET option_value = content/uploads WHERE option_name = upload_path

-- Or set absolute uploads URL
UPDATE wp_options SET option_value = https://example.com/content/uploads WHERE option_name = upload_url_path




Or using WP-CLI:



wp option update upload_path content/uploads
wp option update upload_url_path https://example.com/content/uploads




Note: modern WordPress installs normally do not require setting upload_path WordPress computes uploads location from WP_CONTENT_DIR and WP_CONTENT_URL. Only set these options if you require legacy behavior or a unique location.



6) Adjust plugins/themes if they used hardcoded paths


    

  • Some plugins or themes hardcode /wp-content/ in URLs or filesystem calls. You must update those references.
    • 

  • Search the codebase (or use grep) for wp-content to find hardcoded references and adjust them to use functions like content_url() or WP_CONTENT_URL constant.
    • 



7) Update database references (if necessary)



If the site or plugins saved full URLs pointing to /wp-content in the database (e.g., post_content, postmeta, option values), you must perform a safe search-and-replace that handles serialized data properly. Use WP-CLI or the interconnect/it search-replace PHP script that manages serialized strings.



# Example WP-CLI command: replace URLs but skip GUID column
wp search-replace https://example.com/wp-content https://example.com/content --skip-columns=guid --precise --recurse-objects --all-tables

# If you also moved only plugin path references:
wp search-replace /wp-content/plugins /content/plugins --all-tables --precise --recurse-objects




Important:



    

  • Use the --skip-columns=guid flag to avoid changing GUIDs (commonly recommended).
    • 

  • --recurse-objects ensures serialized PHP objects and arrays are updated safely.
    • 

  • Test with --dry-run first: add --dry-run to preview changes without applying them.
    • 



8) Permalinks and cache flush


    

  • Login to WP admin and resave Permalinks (Settings → Permalinks) to refresh rewrite rules.
    • 

  • Flush any caching layers (object cache, page cache, CDN) so assets are reloaded from the new path/URL.
    • 



9) Verify and remove old folder (only after thorough verification)



Once everything is verified (images load, plugins work, admin media works, no 404/403 for static assets), you may remove /var/www/html/wp-content to finalize the move. Keep a backup snapshot for rollback for at least a short period.



Alternative: Create a symlink (quick and reversible)



If you prefer not to change wp-config.php, create a symlink so the old path maps to the new location. This is quick and often helpful for testing:



# Move wp-content to a new location
mv /var/www/html/wp-content /var/www/html/content

# Create symlink from old path to new path
ln -s /var/www/html/content /var/www/html/wp-content




Pros:



    

  • Minimal changes to WordPress code/configuration.
    • 

  • Instant rollback by removing the symlink and restoring folder.
    • 




Cons:



    

  • Less explicit configuration if you want different URL namespace youll still need constants.
    • 

  • Some hosts do not permit symlinks or change behavior for symlinked directories.
    • 



Serving wp-content from outside webroot (secure or alternative hosting)



You can place content outside the document root for additional security but you must serve it via a webserver alias (Apache) or location alias (Nginx) so assets are accessible via a public URL.



Example: Apache Alias


# In Apache virtualhost configuration
Alias /content/ /mnt/storage/site-content/

    Require all granted
    Options Indexes FollowSymLinks





Then set WP_CONTENT_DIR to /mnt/storage/site-content and WP_CONTENT_URL to https://example.com/content.



Example: Nginx alias


# In Nginx server block
location /content/ {
    alias /mnt/storage/site-content/
    access_log off
    expires 30d
    add_header Cache-Control public
}




Then configure WP_CONTENT_DIR and WP_CONTENT_URL as shown earlier.



File and directory permissions



After copying/moving files, set ownership and permissions appropriate to your environment:



# Example ownership (Debian/Ubuntu typical)
chown -R www-data:www-data /var/www/html/content

# Set directories to 755 and files to 644
find /var/www/html/content -type d -exec chmod 755 {} 
find /var/www/html/content -type f -exec chmod 644 {} 




Adjust the user/group to match your webserver (www-data, apache, nginx, nginx-user, etc.). Be careful not to set world-writable permissions (777).



Multisite considerations


    

  • Multisite stores media per-site under wp-content/uploads/sites/{blog_id} by default. If you move WP_CONTENT_DIR and WP_CONTENT_URL, WordPress will compute multisite uploads from those constants, but test carefully for subsite asset URLs.
    • 

  • Define WPMU_PLUGIN_DIR and WPMU_PLUGIN_URL if your network uses mu-plugins in a different location.
    • 

  • Be aware of domain mapping or external domain configurations that may rely on fixed wp-content URLs in database entries.
    • 

  • For multisite, do not use the UPLOADS constant (it is ignored for multisite) instead rely on WP_CONTENT constants.
    • 



Advanced: Splitting plugins/uploads to separate paths



If you want uploads on a different disk (e.g., /mnt/uploads) and plugins under /var/www/html/content/plugins, set things explicitly:



// Custom content base (for themes and shared assets)
define( WP_CONTENT_DIR, dirname(__FILE__) . /content )
define( WP_CONTENT_URL, https://example.com/content )

// Plugins on a different disk or location inside content
define( WP_PLUGIN_DIR, /mnt/plugins/site-plugins )
define( WP_PLUGIN_URL, https://assets.example.com/plugins )

// Uploads can remain under content/uploads or be served from another domain
// If uploads live at /mnt/uploads and are served via CDN or subdomain:
define( UPLOADS, content/uploads ) // legacy relative example typically you should handle via WP_CONTENT constants and DB options



Troubleshooting


    

  1. Blank page / 500 error

      

    • Enable debugging: set define(WP_DEBUG, true) in wp-config.php to surface PHP errors (temporarily).
      • 

    • Check webserver error logs for permission errors or include failures.
      • 

    

    2. 

  2. Assets 404

      

    • Verify WP_CONTENT_URL is correct and accessible in a browser (try accessing https://example.com/content/style.css).
      • 

    • Check your webserver alias/location if content is outside webroot.
      • 

    • Search DB for hardcoded references to /wp-content and update them (use WP-CLI with --dry-run first).
      • 

    

    3. 

  3. Plugins/themes failing to load

      

    • Ensure WP_PLUGIN_DIR and WP_PLUGIN_URL are correct if plugins are relocated.
      • 

    • Search plugin code for hardcoded ABSPATH or WP_CONTENT_DIR assumptions and adapt.
      • 

    

    4. 

  4. Uploads not storing or accessible

      

    • Check upload_path and upload_url_path options in wp_options table.
      • 

    • Make sure WP has write permissions on the uploads folder (chown/chmod).
      • 

    

    5. 

  5. Serialized data issues

      

    • Always use WP-CLI search-replace or a serialized-data-aware tool. Manual SQL find-and-replace can corrupt serialized lengths and break options/meta arrays.
      • 

    

    6. 



Rollback plan


    

  1. Restore filesystem from your saved archive or move the content directory back to its original location.
    2. 

  2. Remove or revert the constants in wp-config.php.
    3. 

  3. Restore the database from the pre-change backup if you changed many URL references (or use WP-CLI to reverse the search-replace by swapping parameters).
    4. 

  4. Clear caches and re-test the site.
    5. 



Full example: Complete sequence for a safe migration


    

  1. Backup filesystem   DB.
    2. 

  2. Copy wp-content to new folder (rsync).
    3. 

  3. Add constants to wp-config.php (see snippet below).
    4. 

  4. Test site if major errors, revert by removing constants and restoring old folder.
    5. 

  5. If testing succeeds, run WP-CLI search-replace to fix stored URLs (with --dry-run first).
    6. 

  6. Resave Permalinks and clear cache.
    7. 

  7. After several successful checks, remove old folder or replace with symlink for transitional period.
    8. 



wp-config.php snippet (full example):




Checks to perform after migration


    

  • Load the homepage and several posts verify images load and CSS/JS load from the new URL path.
    • 

  • Log into wp-admin and check Media Library thumbnails and upload new media to verify write access.
    • 

  • Activate/deactivate and test plugins, especially caching, security, backup, and CDN plugins.
    • 

  • Run a site crawl or use browser Developer Tools to identify any 404 or mixed-content issues.
    • 

  • Monitor error logs for PHP warnings/notice or webserver errors for missing files or permission denials.
    • 



Final notes and best practices


    

  • Make changes during low-traffic windows and maintain a rollback plan.
    • 

  • Prefer copying files first and switching constants to minimize downtime only remove old files after full verification.
    • 

  • Use WP-CLI search-replace with serialized-aware flags and --dry-run prior to executing replacements.
    • 

  • If serving content from a different domain (e.g., CDN or subdomain), ensure correct CORS headers if needed and update WP_CONTENT_URL accordingly.
    • 

  • Keep a concise changelog of everything you changed (wp-config edits, webserver config, DB updates) to make troubleshooting straightforward.
    • 



Useful commands recap





Copy files


rsync -av /var/www/html/wp-content/ /var/www/html/content/






Set ownership  permissions


chown -R www-data:www-data /var/www/html/content
find /var/www/html/content -type d -exec chmod 755 {} 
find /var/www/html/content -type f -exec chmod 644 {} 






WP-CLI search-replace (dry-run)


wp search-replace https://example.com/wp-content https://example.com/content --skip-columns=guid --dry-run --precise --recurse-objects --all-tables






WP-CLI search-replace (apply)


wp search-replace https://example.com/wp-content https://example.com/content --skip-columns=guid --precise --recurse-objects --all-tables







References



End of article













	
	
Acepto donaciones de BAT's mediante el navegador Brave 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *