How to change your WordPress URL without locking yourself out

WordPress reads its own address from two settings and builds its links, the addresses of its stylesheets and scripts, and its login redirects from them. Changing the site's address means changing those two settings, and then dealing with the copies of the old address that are stored everywhere else.

That covers a new domain, a move from http to https, adding or dropping www, and moving a site out of a subfolder. The steps here are for a single site. A multisite network keeps its addresses in more places and is moved differently.

The two settings

Both are under Settings, then General.

• "WordPress Address (URL)" is the address of the folder that holds WordPress's own files, such as wp-admin and wp-includes. In the database it is the option named siteurl.
• "Site Address (URL)" is the address people type to reach the site. In the database it is home.

WordPress's documentation says the two are identical unless WordPress has been given a folder of its own. So on most sites you change both, to the same value. Write the full address with https:// in front and no slash at the end.

Before you change anything

• Take a backup of the database and the files. With WP-CLI, wp db export ~/before-address-change.sql writes the database to a file in your home folder. Download it, and delete it from the server when you are done.
• Check that the new address already reaches the server. For a new domain, add it to your hosting account and point its DNS there first.
• Check the certificate. Open the new address with https:// in front. A certificate lists the names it is valid for, so one issued for the old name does not cover the new one. If the browser shows a warning, fix that first: see how to fix "Your connection is not private".
• Try it on a staging copy of the site first, if you have one.

Four ways to change the address

Use the first one that is open to you.

In the dashboard

If the two fields are greyed out, the addresses are defined in wp-config.php and have to be changed in that file.

In wp-config.php

Two constants overrule what is in the database: WP_HOME for the Site Address and WP_SITEURL for the WordPress Address. Add them above the line that says "That's all, stop editing!".

define( 'WP_HOME', 'https://example.com' );
define( 'WP_SITEURL', 'https://example.com' );

This works when you cannot reach the dashboard, which makes it the quickest way back in after a mistake. It does not change the values stored in the database, and while the lines are there the two fields under Settings cannot be edited. To make the change permanent, set the same addresses in the database with one of the other methods, then remove the two lines.

With WP-CLI

Over SSH, from the site's folder. The first two commands show what is stored now, and the last two change it.

wp option get home
wp option get siteurl
wp option update home 'https://example.com'
wp option update siteurl 'https://example.com'

If wp-config.php defines WP_HOME or WP_SITEURL, those still win.

In the database, as a last resort

With no dashboard, no WP-CLI and no way to edit wp-config.php, change the two values by hand. Back up the database first. In your host's database tool, usually phpMyAdmin, open the wp_options table. The prefix may differ from wp_. Find the rows named siteurl and home, which may be on different pages of the table, and edit the option_value of each.

Change those two values and nothing else. Do not use the tool's find and replace on the whole database.

Replace the old address stored in your content

The two settings are not the only place the address lives. An image placed in a post is saved with its full address. So are links between your pages, and many theme and plugin settings. After a change of domain those still point at the old one. After a move to https they still say http://, which is what causes mixed content warnings.

A plain find and replace, in a database tool or in an exported .sql file, breaks some of them. Themes and plugins store many settings as serialized data, which records the length of each piece of text beside the text. WordPress's documentation puts it this way: values are stored "with the length of your URL marked. When this changes, things break." Swap in an address of a different length and the recorded length no longer matches, and the setting cannot be read.

WP-CLI's search-replace command handles serialized data and corrects the lengths.

--skip-columns=guid leaves alone the permanent identifier WordPress gives each post. Feed readers use it to tell which posts they have already shown, and WordPress's instructions are never to change it, even when the domain changes.

The command searches the tables WordPress itself registers. Add --all-tables-with-prefix to include tables that plugins have added.

Without WP-CLI, use a search and replace plugin that says it handles serialized data and offers a dry run. WordPress's documentation names Better Search Replace for this.

Moving out of a subfolder

To move a site from example.com/blog to example.com, the order matters. WordPress's instructions are to change the two addresses under Settings, then General first, save, and only then move the files, without opening the site in between. Then log in at the new address, go to Settings, then Permalinks and press Save Changes so that the rewrite rules are written for the new location, and run the search and replace above for the old folder's address.

If you move the files first, the settings still name the old folder and the dashboard will not load. Set the two addresses in wp-config.php to get back in.

Redirect the old address

Anyone who follows an old link, and every search engine that knows the old address, should land on the same page at the new one.

For www this takes care of itself when both forms reach the same WordPress: it sends visitors to the host name in the Site Address. For http to https, many hosting control panels have a switch that forces HTTPS. If yours does not, ask the host to add the redirect. For a new domain, add a redirect on the old domain that keeps the rest of the address. Your hosting control panel may have a tool for this. By hand, it looks like this:

RewriteEngine On
RewriteCond %{HTTP_HOST} ^(www\.)?old-example\.com$ [NC]
RewriteRule ^(.*)$ https://new-example.com/$1 [R=301,L]

On Apache the rules go in the .htaccess file of the folder the old domain is served from. If that file also holds WordPress's rules, put these above the line # BEGIN WordPress. On nginx, the old domain's server block for port 443 needs the same return line beside its certificate settings.

Keep the old domain registered and its certificate current while the redirect runs. A browser checks the certificate before it follows the redirect, so an expired one stops visitors at a warning.

Do not send every old address to the new home page. Google's guidance is to redirect each old address to its own new one, in one step.

Tell search engines

Redirects do most of this. Google treats a new domain and a move to https alike as a site move, follows permanent redirects and passes what it knows about the old addresses to the new ones.

• Verify the new address in Google Search Console, and keep the old one verified.
• For a new domain or subdomain, use the Change of Address tool there. Google says it is not needed for a move to https or between www and no www.
• Submit the sitemap at the new address. WordPress's own is at /wp-sitemap.xml, unless an SEO plugin provides a different one.

Google says to expect rankings to move about while it reads the site again, and that for a medium-sized site it can take a few weeks or more for the new addresses to show.

If the new address locks you out

A mistyped address, or one that does not reach the site yet, leaves the dashboard unreachable or the login page reloading. Nothing is lost. Add the two lines from "In wp-config.php" above with the address that does work, using your host's file manager or SFTP. The site answers at once and you can log in.

Then put the right values in the database, under Settings or with WP-CLI, and remove the two lines. If the login page still keeps coming back, work through the login page that keeps refreshing.