Documentation

WordPress Core Installed in a Subdirectory

Last updated January 18, 2022

WP Migrate DB Pro supports migrations to/from WordPress installations where WordPress core is installed in a subdirectory of the same name on both sites. However, we do not support migrations where WordPress core is installed in the default location for one website and installed in a subdirectory for the other site.

Supported Migrations

The following is supported:

  • Default installation → Default installation
  • WP core in a subdirectory installation → WP core in a subdirectory installation

And the following is not supported:

  • Default installation → WP core in a subdirectory installation
  • WP core in a subdirectory installation → Default installation

Please also note that for installs where WP core is installed in a subdirectory, the name of the subdirectory should match on both websites, i.e., if using the directory “wp”, both WordPress installations should use the directory name “wp”. Please don’t mix and match the directory names.

Why You Can’t Migrate a Default Install to a WP Core in a Subdirectory Install and Vice Versa

The difficulty in migrating between default and subdirectory installs is how WordPress handles URLs for items like images or files compared to how it handles URLs for posts and pages.

WordPress uses absolute paths to files. For example, when you add something from the Media Library to your post or page content area, WordPress will add the HTML element with an absolute path to the file. Below is an example of an image added to the post content.

<img src="https://hellfish.media/wp-content/uploads/2021/11/2560px-Macbook-1024x768.png" alt="This image has an empty alt attribute; its file name is 2560px-Macbook-1024x768.png">

Now, if you had added the same image in a subdirectory install (using our examples above) the absolute URL would include that subdirectory in the URL.

<img src="https://hellfish.media/wp/wp-content/uploads/2021/11/2560px-Macbook-1024x768.png" alt="This image has an empty alt attribute; its file name is 2560px-Macbook-1024x768.png">

If you’re migrating from a subdirectory install to a default install (or vice versa) you might think all it takes to fix this is a simple Find & Replace where you replace //hellfish.media/wp with //hellfish.media, or //hellfish.media/ with //hellfish.media/wp. However, this doesn’t take into account how WordPress handles URLs for posts and pages.

WordPress posts and pages—and practically any other content that is dynamically generated by WordPress—do not have a physical path on the server in the same way that a file does. So, for example, a URL to an About page could be https://hellfish.media/company/about/, but there isn’t a folder in the webroot called company that contains a folder called about. This is a permalink that WordPress understands and uses to generate the content for the About page. This is known as “routing” in software development.

What makes the find and replace process a problem is if you’ve created links in your content to any posts or pages elsewhere on your site. For example, from your About page, you might have added a link to your Careers page, which could be https://hellfish.media/company/careers/. This link would be saved in the content field in the database. If you migrate to a subdirectory install and run the “find and replace” example to add the subdirectory path, it would turn this URL into https://hellfish.media/wp/company/careers/ and the link would be broken.

An Example

We can show you what would happen if we attempt to migrate from a site that has core files installed in a subdirectory, to one which has core files installed in the root. For this example we’ve set up two local sites, https://hellfish.test and https://subdir.hellfish.test. On the second one, https://subdir.hellfish.test, WordPress is installed in a subdirectory named wp. We’ll be pushing from https://subdir.hellfish.test to https://hellfish.test, including new and updated media, as well as the active theme. We’ve also created a very basic page to serve as the site home page, which includes an image in the page content, and a link to a Contact page.

This migration will use the default WP Migrate DB Pro settings.

WP Migrate DB Pro push migration settings.

The results of hellfish.test after the migration don’t look amazing:

A broken site after attempting to push from a subdirectory.

Immediately you can see that the CSS styles and images are not loading. If you inspect the source using dev tools, you’ll find JavaScript isn’t being loaded either. As we pointed out earlier, this is because they are looking for the paths at https://hellfish.test/wp/. Even attempts to access the dashboard go to https://hellfish.test/wp/wp-login.php, which presents a “Page not found” error.

We often receive support requests from people attempting to perform a migration where one site has the core files in a subdirectory and the other does not, which we don’t support. This is because sites would need a conversion to the same type of install before you can carry out a successful migration. We also don’t support migrations between subdirectory installs where the subdirectory names are different, for the same reasons.