Rename a Custom WordPress Theme

by

Recently, I found myself in a situation where I needed to change the name of a custom theme for a WordPress site. I found a lot of information online about how to name a theme, but only if you were just starting a new theme, not changing the name of a theme in place on a live site. So, I thought I’d right down the steps I took, in case anyone else ever needs to do this.

This particular problem arose because I had started prototyping a WordPress theme for a client at work, and then I enlisted another developer to flesh out the final theme. Due to a misunderstanding, the other developer just built on top of my prototype theme. Because I thought that he would name his theme after the site name, I had used the name of the starter theme on which I based my prototype. (By the way, I highly recommend this starter theme, Handcrafted WP by Randy Hoyt and Randy Jensen, as an excellent base for a theme without all the complication of making a child theme.) What I ended up with was a theme named themename, in a directory called  /handcrafted-wp-theme-master.

I could have just changed the displayed theme name, at the top of the theme’s style.css file, from themename to the name of the site, but that would have been technical debt that may have been expensive to pay off down the road. Instead, I performed the following steps.

(Note well:  Always back up all your site’s files, especially the /wp-content directory where theme files live, and back up your database, before you attempt this.)

Step 1. Display a maintenance message while you work

This is not absolutely necessary, but because the site was already live, I did not want visitors to see a different or broken them, even for a few minutes. In this case, I used the Under Construction plugin by Jeremy Massel. Unlike the automatic update maintenance mode, this plugin allows you to preview the site and work in the admin area, while showing other visitors a customized maintenance message.

Step 2. Change the site to a default theme

To be safe, I changed the site’s theme to Twenty-Twelve. Again, this may not be absolutely necessary, but I think doing this will help guard against corrupting any options in the database. (Always leave one of the WordPress default themes in your install, for cases like this.)

Step 3. Disable the theme in your Network Admin area (Multi-Site WordPress only)

This step is only necessary if your site is part of a WordPress Mulit-Site network. My site was, and I found I could not re-activate the theme once I renamed its directory unless I did this. This has to be done in the Network Admin area. Choose My Sites > Network Admin > Dashboard from the admin bar, and then choose Themes from the left menu. Find your theme in the list and choose Network Disable. (DO NOT actually delete the theme, just disable it.)

Step 4. Change the name of the theme in its style.css file

Open the theme’s style.css file and find the line in the initial comment that begins with
Theme Name:. This is the name that is displayed in the WordPress admin area. In my case, this line read:

Theme Name: themename

I changed “themename” to the name of the site, in Title Case, for display purposes.

Step 5. Find and replace the theme’s text domain name in all theme files

If your theme declares a text domain, as the Handcrafted WP starter theme does, it is a good idea to change the name of that text domain to match the new name of the theme.

You can do this with any text editor that has multi-file find-and-replace. In my case, I had SSH access to the server, so I just ran this at the command line:

grep -lr -e 'themename' * | xargs sed -i 's/themename/example/g'

(This works on Ubuntu Linux. Your operating system may require syntax. Or course, change “example” to the name you are using.)

Step 6. Rename the theme directory

Change name of the theme directory in the /wp-content/themes/ directory.

Step 7. Turn your theme back on.

First, reverse Step 3 (if necessary) by re-enabling the theme in the Network Admin panel. Then, make the theme the active theme on your site.

Step 8. Copy any theme options in your database to entries under the new name

You’re not quite done yet. At this point, if you browse through the public pages of your side, you’ll notice at least one disconcerting fact. Your sidebars have disappeared! Don’t panic. The sidebars are still there, but if you look in the Widgets screen of the admin section, you’ll see that any sidebars appear to have lost their widgets. That’s because WordPress saves the list widgets for each sidebar of each theme in its options table under the theme’s folder name. You just changed the theme folder name; so, of course WordPress can’t find those lists of widgets.

The fix is simple. Look in options table of your WordPress database—you can use phpMyAdmin or any database tool that allows you to modify the database, even the command-line mysql command—and look for an entry with the option_name of “theme_mods_<old-theme-name>”.  (Replace “<old-theme-name>” with, you guessed it, your old theme name.) Copy the value in the option_value field of that entry to the option_value field of the entry with the option_name of “theme_mods_<new-theme-name>”, where “<new-theme-name>” is your theme’s new name. This will restore your sidesbars.

There may be other options with the theme’s old name that need to be copied. You could actually just go and redefine those options again, now that the theme has a new name, if there aren’t too many of them. If there are a lot, you can try to copy theme with SQL statements.

9. Turn off your maintenance message

Once you are satisfied that the site’s theme is displaying correctly with it’s new name, don’t forget to  turn your maintenance message off.

I hope that these steps will save some hair-pulling if you find yourself in a situation similar to the one I was in:  having to rename a theme on a live site.