How the WordPress Upgrade Works

Every time WordPress upgrades, someone is going to bitch that WordPress 'deleted' their stuff. Guess what? It can't.

Edited: This post was linked to by the folks at WTC, so I’m getting a lot more traffic! If you asked a question, I will try to answer it promptly, but if you need serious help fixing a problem, please consider posting in the WordPress forums for help.

I was 90% sure about this before I started writing the post, and Andrew Nacin was nice enough to tweet me the exact file I needed to look at, so when I got home to look, I was ready to go!

There are two kinds of automated upgrades for WordPress. The main ‘core’ upgrader and then the ‘child’ upgrades used for themes and plugins. They behave differently.

Most of the time, we all see the plugin and theme installer, where it downloads the plugin to /wp-content/upgrade/, extracts the plugin, deletes the old one, and copies up the new one. Since this is used more often than the core updater (most of the time), it’s the sort of upgrade we’re all used to and familiar with. And we think ‘WordPress deletes before upgrading, sure.’ This makes sense. After all, you want to make sure to clean out the old files, especially the ones that aren’t used anymore.

This is not how a core update works.

WordPress core updates, the ones to take you from 3.0.3 to 3.0.4, do not run a blanket delete. They don’t even run a variable delete. They don’t even run a wild-card delete on files in wp-admin (which they could). Instead they have a manually created list of files to delete, files that have been deprecated, and delete only those files. Here’s a snippet of what it deletes:

$_old_files = array(
// MU

// 3.1

As you can see, the files and folders are all very carefully specified. They are not ac-hoc, they are all determined based on what WordPress has removed. If you read the whole thing, the part that would impress you the most is, perhaps, the folder wp-content, where your themes and plugins are installed, is nowhere on that list. Don’t believe me? Go look at wp-admin/includes/update-core.php and search for it. It’s not not there!

Once the old files are listed, remember that we have not deleted anything, the upgrader runs through 9 steps.

  1. Download the zip file of the new release, unzip it and delete the zip
  2. Make sure the file unzipped!
  3. Make a .maintenance file in WordPress base (this makes your blog ‘down for maintenance’ so no one can do anything and screw you up mid-stream
  4. Copy over the new files. This is a straight copy/replace. Not delete.
  5. Upgrade the database. This may or may not happen.
  6. Delete the unzipped file
  7. Delete the .maintenance file
  8. Remove the OLD files. This is where it goes through the list of deprecated and unused files and deletes them.
  9. Turn off the flag that tells you to upgrade every time you’re in wp-admin

Nowhere in there is wp-content and your themes mentioned.

Well, except in this one weird way.

See, in order for WordPress to work out of the box, a theme must be included, right? WordPress has the default theme of Twenty Ten. Now, I’ve mentioned before that you should never update your themes directly, and instead make child themes. This is why. When the WordPress core files update the copy over everything. Included in everything are two plugins (Akismet, Hello Dolly) and one theme (Twenty Ten).

Normally this isn’t a problem. Sure, someone always edits those files directly and lives to regret it, but they do live. This last cycle, with 3.0.4, Akismet was accidentally rolled back from 2.5.1 to 2.4. Again, normally? Not a problem. We just upgrade our Akismet installs, remark on the silliness and annoyance, and move on. The problem for one user is she had another plugin or theme edit that hooked into the new Akismet. With the way WordPress updates core, it only deletes the files it knows to delete (and Akismet isn’t any of them) and it copies over the ‘new’ files. Or in this case, the old ones. Which broke her site. Her fix? Just re-update Akismet manually. Not a big deal and an easy fix. (Personally I think NOT updating core, even a security upgrade, with the latest Akismet is a poor choice, but the rational is that they want to keep it small and easy to maintain. So okay, I get why, I just don’t like it. I will support that as their choice, and continue to do my manual upgrades, which include deleting Akismet, Hello Dolly and Twenty Ten before I upgrade.)

So then, why doesn’t this work 100% of the time? (Yes, I mentioned this before in the 3.0.1 days, but apparently it bears repeating. Read Why doesn’t the WordPress Auto-Upgrade Work? for more thoughts on the subject.) Well, to start with, that’s impossible. Nothing works 100% of the time. Me submitting this post won’t work 100% of the time. You safely walking up the stairs won’t work 100% of the time. This is just how the world works. There are, simply, far too many variables out there to allow this. Even though I make part of my living ensuring that I have an automated process run in a repeatable fashion, I tell people that I only ask for a 75-80% success ratio on the process before I’ll agree to automate it. Why? Because that’s actually phenomenal.

If you take into consideration all the moving parts, variables, and possibilities that goes into any one individual WordPress install, it’s sort of impressive this stuff works at all. In baseball, if you hit a ball and get on base 33% of the time, you’re considered a fantastic hitter. If you do it 40% of the time, you’re pretty much promised a slot in Cooperstown. Whenever I try and sort out if something is worth the risk, I quote my father “What can go wrong? How likely is it? What are the consequences?” It boils down to an understanding of risk analysis, and what that actually means. The problem is that most of the people using WordPress are users. They’re not generally expected to think about risk. Not that many don’t, but just that Joe Blogger doesn’t tend to look at an upgrade as a ‘risk.’ After all, WordPress tested this, so it should be easy.

Most of the time, it is. And when it’s not, it was an acceptable risk. All those horrible and terrifying outcomes you read about (from a very vocal minority) are gut-wrenching when they happen to you, don’t get me wrong, but at the end of the day, you have to ask ‘If I use the default WordPress theme and no plugins, do they happen?’ If the answer is no, then WordPress has done all the testing that is required. The onus is not on WordPress to test every upgrade with every theme and plugin. That responsibility is firmly on the shoulders of the person using the themes and plugins. A good developer tests their plugins and themes the moment a release candidate comes out for a new version of WordPress, and sorts out how best to support both the current users and the future ones.

It’s what we call ‘acceptable’ risks. You take them all the time. You took an acceptable risk brushing your teeth. You take one every time you walk out your door. You know the risks and you accept them. So when you get to arguing that ‘WordPress upgrades always break’ or ‘I hate upgrading because it means my themes/plugins won’t work’ and using these as reasons to show that WordPress is bad software, then I think you’re missing the point. The more you customize, the more things break. This is something I mentioned in When To Code, and it bears repeating. The more you customize, the more things will break when you upgrade.

But this is an acceptable risk for most of us!

So when the WordPress auto-upgrade breaks, and I promise you, it will for you at least once in your experience, you have to learn to accept this. It’s not going to work on every server, it’s not going to work on every host. Your server is being constantly upgraded and tweaked. Security patches for PHP, FTP and everything else are applied, most of the time automatically so you don’t have to waste time thinking about it. And when you combine all those things, yeah, it’s going to break.

This isn’t meant to scare you off of upgrading, but an attempt to raise your awareness of what’s going on, so when things break (and they will), you have a better understanding of why, and what to do. If the automated upgrade of WordPress breaks, upgrade manually. If every single automated install (upgrades, plugins, themes) always breaks, then start to diagnose your server. But if it’s a one off, just do it manually. It is, literally, copying files up to your server. If that’s too hard for you, you may not want to run your own, self-managed, WordPress install.

As a blanket reminder, in order to prepare yourself for an upgrade, always make backups of your database and your files. A good backup. Never edit core files (even themes) and always remember that the computer is out to get you.


    • They manually make it themselves. That deprecated list is ONLY for WordPress core files, which means, ta dah! It never touches YOUR plugins and themes 🙂 Safe as houses.

      By the way. Your URL has the word ‘wordpress’ in it, which is in violation of the WP trademark policy. You may want to reconsider that.

  1. Dear sir,
    Your article is quite useful and it simply says to expect ‘breaks’ in core files, themes, plugins, etc. I understand it in theory, but as I am new to WP, it may take some time for me to master all these. So, I think, if the automatic updates takes care of other aspects, not including server or host sides, it would have been far better. Is there a way to stay with a particular version of WP?

    • Well everything breaks 🙂 if you can find me a perfect system, then I have a bridge to sell you…

      The automatic upgrade is something I consider safe. It works, most of the time, but math being what it is, it WILL fail eventually, so be prepared. I actually tell my dad to use it on his site, and it works just fine there. For myself, I use my own scripts because I can add in commands to backup SQL first, and save myself some headaches.

      Don’t be afraid of the automatic upgrade. And while you can avoid it just by not running it (ALL upgrades are optional!) I strongly urge you to keep up to date with upgrades. There’s a reason for them, and the odds are you will regret not upgrading more than you will regret an upgrade.

  2. I used to have to cross my finger while updaing core on my WordPress sites. Now i just dl newest (3.0.4) from .org to my pc , unzip, delete wp-content and the config-sample files then FTP the rest to a sites root.I use FTP for themes and plugins because the system built in is too un reliable and just sits there with no feedback as to whats going on. After 10-15 mins I would just FTP it anyways.
    This in no way make me unhappy with WordPress the many other things about it makes up for that part.
    Great discription of the way it works!

    • Yeah, a lot of hosts throttle the way FTP works over PHP. The two popular FTP apps are proFTP and PureFTP and one of them JUST had an upgrade that broke everything.

      My only suggestion would be to use SFTP 🙂

  3. You said it man. Love this. Great post. Everyday more bloggers are joining the ranks and many can barely use a computer. They don’t understand how important it is to update their self-hosted WordPress blog but complain when it breaks because their “expert” developer did a crappy job with their theme or possibly they are using a out-dated and unsupported plugin. That isn’t WP’s fault and realizing what WP does is actually quite remarkable.

    Thanks again!

  4. I was using Kubrick a couple of times in the past. I’ve noticed then the Kubrick theme files were being overwritten after each upgrade. It’s the same with Twenty Ten. Yes, it’s all the more reason to use child themes or a completely different theme entirely. By the way, I use Subversion update for all my blogs now. Only files that have changed are updated.

    • Subversion’s a great way to go, though it’s not the … mmm … easiest? It is for people copacetic with command line, but honestly, I think not even half the people using WP today are! I use SVN on this domain, most of the time, or my own script to pull down the Nightly Build. I left it out of the post since it’s worth its own topic 😉

  5. Thanks for the explanation, it was great.

    I currently use Bluehost, so I administrate my blogs via Simple Scripts. If I decided to update my blog via the automatic upgrade link on my WP backend rather than the Simple Scripts website, will something (like Simple Scripts) break or will it be fine?

    • Everything breaks at least once. Make a backup first, always, no matter what method you use. When I was new at all this, I did use Fantastico, but I found myself frustrated because the upgrade was always behind the official release. I don’t like waiting on someone else for a security release.

      My caveat here is I don’t use BlueHost (the ad for LiquidWeb on this site is because I use and adore them).

      I’m torn at saying which tool to upgrade is ‘safer’ since I want to say “WordPress is safer! They test it!” but then I want to say “BlueHost’s script, if they write it themselves, is better since they wrote it FOR their environment.” I think I have to say they’re equally safe (and equally risky) but if you pulled a gun on me, I’d always use the WordPress upgrade tool first.

  6. Could you please wise me up as to what happens to the translation files (.mo) when the plugins and themes are upgraded automatically, especially if they are not in a separate folder called “languages”?



    • .mo files are left alone.

      The ONLY warning I have about those is you should put them in /wp-content/lanuages/ and not your wp-includes (because if the install gets corrupted, we always tell people to delete wp-includes and wp-admin!

  7. Got linked to this article via WLTC and really enjoyed reading it, thanks – especially as I am an end-user. So far so good for my auto-core upgrades, but it’s really nice to finally find out how the Upgrade Process works in lay-man terms, and also to highlight again that there is a risk with upgrades, so that people (like myself) remember to not become lazy and have a back up plan.

  8. I’ve wondered about this for quite some time actually. I was curious if WordPress deleted all the files in a core update or not, and if not always, then when would it. Thanks for finally explaining it.

  9. I really think our company blog needs updating.

    It was installed way back before it became my responsibility. It uses WP version 2.8.something. I would like to auto-update it to the latest – WP version 3.0.4?

    Is exporting and saving the XML file, enough assurance for me to regain the blog should auto-upgrading version messes things up?

    • Only if all you care about is the data.

      Backup your database and all the files. It’s pretty easy, but yeah, you totally should upgrade. There are known security holes in 2.8

  10. I was feeling pretty ripped today about the whole automatically updating to 3.0.4 and all the plugins. Nothing went right but this stuff is all FREE right. How can you really complain?

    As Bob Dylan said, “Everything is broken”

    • Everyone can (and has the right to!) complain, but there’s a difference between complaining to just bitch that it all sucks, and being helpful to make it better.

      My problem with the complainers is that they’ll tell you it sucks, but not want to take any of the work on themselves. They want the magic clicky box to work perfectly, without taking a moment to consider everything that goes into making it work at all. They want the upgrade to work without thinking ‘I added a ton of plugins and hacked my theme to hell and back over the course of a month! I wonder if that might affect things.’

      Complain 🙂 Everyone does. I do. But don’t let your complaints stop you from using your brain to think rationally about the problems.

  11. Very interesting and useful content, Ipstenu

    Does WP offer a package with just the files that have changed from the previous version?

    I tried to automatically upgrade from 3.1.2 to 3.13 and I get the usual memory error below. Problem is my hosting co is 1and1 and they limit memory to 30M even if you change the htaccess etc…

    Fatal error: Out of memory (allocated 31981568) (tried to allocate 2897881 bytes) in /homepages/10/d250354628/htdocs/growthroute/blog/wp-includes/class-http.php on line 1420

    I don’t want to have to reinstall all files every time because I did alter a couple (no-no I know, but I did as it was faster). Now if those have changed, I would reinstall them. But otherwise it would be a waste of time at every upgrade since I would need to manually recreate my changes even if the file hasn’t changed. Or check whether it has. Either way: pain.

    So do you know if there is a download anywhere with just the files that changed?

  12. I manually replaced all those files and Admin still tells me to update to 3.1.3.
    Any idea how I can notify it it is updated?
    (This 1and1 memory limit is a true pain.)

    • *cough* I would suggest taking the time to make your changes ‘right’ 😉 Plugins, functions, etc. Then you can just overlay and not care.

    • Definitely was in my list of to-dos. Along with a thousand other things… 🙁

      I’ve learnt about a million things about wordpress in the past 3 months and I’m a *just* a commerce guy so I’m reaching a bit of a saturation point (and need to start making $ again…). 55 plugins installed on my blog so far, many of which customized directly in the php for my purpose. Check it out! (click on my name)

Comments are closed.

%d bloggers like this: