Upgrading to WordPress 2.3.1

For the longest time I let my blog remain on the 2.02 version of WordPress. One of the reasons that this was the case is that upgrading WordPress used to feel like a potential nightmare. While I am moderately technical, I am no web server geek by any means, and in the past there were steps in the process that felt like they would require me to be one to make sure everything went smoothly.

However, when I checked out the procedure for upgrading to WordPress 2.3.1, it suddenly seemed quite a bit easier to take on. So two weekends ago I took the leap and did it. I do have to say that the Basic WordPress Upgrade Instructions seemed inadequate.

I went straight to the Extended WordPress Upgrade Instructions. Even when I got there, I skipped the overview provided and went straight to the detailed instructions. This is a must do, because it’s only here that you get all the details of everything you need to do. For example, it is only here that we see that there are certain files from the old version that you do not want to delete.

With the detailed instructions everything was fairly straight forward. Plan on allocating a solid continuous 2 hours to do the upgrade, and more if you have done customizations of your theme files (because you will need to redo these). Also, be aware that your blog will be down during this process. Users will not see your content.

As a result, you should plan to do this upgrade at a very low traffic time for your blog. You may also want to provide a temporary web page to replace your blog during the upgrade to let people know that it is going through maintenance. In addition, if you are not technically very adept, make sure you have help available in short order if something goes wrong (I did).

Here is a summary of how it went:

First steps

1. The first thing I needed to do was back up the SQL database file. This is where all the blog posts for your blog live, so you want to make sure you have this backed up. You should, in fact, back this up regularly any way.

If you do not know how to executve this step, hold off on the upgrade until you have found someone who will do it for you. In my case, I leaned on the expertise of my partner, John Biundo, to take care of the backup (he has also set it up so the STC blog gets backed up on a weekly basis automatically.

2. The next step was to back up all of the files in the blog directory on my server. These are all the WordPress 2.02 files. I copied them to a separate directory on my PC. This was a very simple step. One drag and drop in my FTP client, and I was done.

3. This is the step is what the WordPress instruction calls “the most important step in the upgrade process!”. Personally speaking, I looked at the files, they were on my hard drive, end of story. In any event, don’t be too alarmed by this step in the process. Yes – it is important. It’s there to save your bacon if something else goes wrong during the upgrade process.

However, if you are patient, and take your time at this, you should be in good shape. Nonetheless, do not skip the backup setps, or the verification step (ideally verify that you can open the files).

Getting Down To It

4. Hext step is to deactivate all of your plugins. The reason for this is that some of the plugins may conflict with the upgrade process. Easy to do – just go to the Plugins menu and deactivate them one at a time.

5. Next, I donwloaded the WordPress Upgrade Package from the WordPress site onto my hard drive. I put this in a different directory from the one where I put the backed up version. One folder I called WordPress 2.0.2 (where I put the old files) and the WordPress Upgrade Package I put into a folder called WordPress 2.3.1.

In theory, you can go straight to your web server with the files, and unzip them there, but I knew I was going to have to customize the theme files any way, so I wanted to have all the files on my hard drive as well.

6. The next step was to delete the old WordPress files from our web server. Be careful! This is one of the areas where it’s only in the detailed instructions that it explains that there are files that you don’t want to delete. Take your time on this step, and make sure you know exactly what to delete and what not to delete. Failure to do this accurately will cause more work for you later.

I chose to interpret the instructions from WordPress on this point very literally. It may feel silly to not delete a file that you know is going to be overwritten any way, but the more important part of this is that there are files that are not going to be overwritten, and following the WordPress instructions precisely does work (it worked for me in any case).

I used my FTP client to handle the deletions and this took place without any problems.

7. Upload the new files! You are almost through the basic part of this process. The detailed instructions tell you that you must upload everything but the new wp-content folder first, and then you can upload wp-content after everything else is up first. Note that I did not do that quite so precisely as all that – but I would not ignore the advice if I were doing this again.

8. Next up is to run the upgrade script. All you need to do here is open your web browser and open up http://www.yourdomain.com/Your-Wordpress-Folder/wp-admin/upgrade.php. If you have WordPress installed at the root of your site (i.e. the blog is your site), then you can simply invoke http://www.yourdomain.com/wp-admin/upgrade.php. This part of the process took me no more than a few minutes.

9. According to WordPress, the next step is to update your Permalinks and .htaccess file. You start by checking Options->Permalinks to see if there is anything you need to adjust (for example, if you overwrote the config file when you uploaded your files, you may need to set these options again).

In addition, if there is any reason why you would need to update your .htaccess file, this is the time to do it. In my case this was not necessary.

Approaching Paydirt

10. Now here is a step I added to the process – go check your blog and make sure it’s breathing. The plugins will all be deactivated, and any customizations you did to your theme will be missing, but it should be there. Just make sure before you go any further.

11. Go get the latest versions of your plugins. I first downloaded these to the plugins folder in my WordPress 2.3.1 folder on my hard drive, so I’d have them there. Then I uploaded them to the correspnding folder on my web server.

12. Reactivate each of your plugins and make sure that they work. I did this one at a time in sequence. I did have one of my plugins that did not seem to work quite right, but I can live without it, so I deactivated it and moved on.

13. Redo any code customizations you have done to your theme. I use the default theme, and whenever I edit a file in the theme, I save the original file to a different file name (e.g. sidebar.php.original), and then clearly mark my changes with comments, such as “<!– Code Added by Eric –>. Since I did this when I customized the 2.0.2 version this made this stage much easier.

I simply went to the 2.0.2 version of each edited file, found the customizations, and ported them manually into the new (2.3.1) version of the file. Once I had completed each change, I uploaded it, and then tested it out and made sure it was working before I made the next change.

Take it for a Real Test Drive!

14. Once all your customizations to the code (if you had any) are back in, you should be in good shape. Check out your blog home page, some permalink pages, category pages, date archives, and any special pages that you have. Make sure they look like they are all in good order. If anything does not look right, the chances are that one of your code customizations was not done quite correctly.


Do plan on this taking at least 2 hours, and more if you have code customizations to do. Be very meticulous about it, and make sure you take each step in the same order as described in the WordPress instructions.

Upgrading is worthwhile. For example, there are plugins I wanted to install (such as the Yahoo Shortcuts for WordPress Plugin that will not run on 2.02.

In addition, one of the major reasons is to reduce your vulnerability to hackers. Hackers are a fact of life on the web today, and software providers, such as WordPress, are frequently releasing updates that fix security holes. This is a major reason for staying current, or near current.


  1. says

    Looks like clear directions. I found several sets of instructions that weren’t or conflicted.

    I just went through this with one of my blogs. Quite the adventure, only because I spaced one freaking detail. That’s the thing with WordPress — make an error, pay the price.

    I didn’t find the help forums any help. Just kept trying to figure it out until I did. Took three days. Learned a lot while clanging around, though.

    Yes, back up very carefully. If I hadn’t the blog would have been toast.

  2. Jo says

    2 hours! Thanks for the detailed instructions but I’m not sure I want to commit my time to WordPress if it takes that long. I only just started using it and it’s not so easy. How often do I need to update?

  3. says

    Yup – it’s a non-trivial activity to update WordPress. As for how often you should update, that’s really a risk based call. The risk of not updating is that some hacker will exploit a security hole in your older version and mess up your blog.

    However, if you just started, you are not a very likely target for a hacker (but your risk is NEVER zero).

    The other major factor is how old your version is. If you are on a really old version (I was on 2.0.2 which was pretty old) you may find certain plugins you want to use that you can’t work with because they require a later version.

    So it’s a judgment call you need to make for yourself. If you are not worried about the security risk, and you are not missing any functionality you care about (either in the software or a plugin), then you might want to wait a while.

    My own opinion is that I waited too long. I’d be tempted to update on every update affecting the digit to the left of the first decimal point or the digit to the right of the decimal point.

    Since I am on 2.3.1 now, this would mean either a 2.4.x update or a 3.x.x update.

Leave a Reply

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