How to Upgrade from Drupal 5 to Drupal 6 - Step 1: Planning

mindmap of drupal 5 upgrade Yesterday I posted an article about why you should upgrade to Drupal 6. Today I'm writing the first of a series of posts on how to upgrade, in an effort to make sure you have no excuses not to.

When you download Drupal it comes with an 79 line document called UPGRADE.txt. UPGRADE.txt is essential reading when going through an upgrade. So important in fact that you should go and read it now and come back.

Done? Very good. As you can see, the document only covers the mechanics of an upgrade. Important information indeed, but it doesn't include any of the dozens of things you may need to do even before you get started. You should not open the document and start executing the steps without planning ahead. If you jump right in you may get to step 9 (Re-install contributed modules) and find that there isn't an upgrade path for one of the contributed modules you use.

So as you may have guessed, the first thing you should do is start formulating your plan. The plan I created for the upgrade of this site had 4 basic phases:

  1. The "before you do anything" phase which includes:
    • module inventory
    • research module upgrades
    • documenting the plan
  2. The "getting Drupal 5 'upgrade ready'" phase. i.e. Actually doing things to your Drupal 5 site before you are ready to start the upgrade
  3. The "actually upgrading to Drupal 6" phase
  4. The "testing and deployment" phase

Today, I'm only covering the first phase.

Before you do anything: Planning Part 1 - Module Inventory

If this is your first Drupal upgrade you may not know that contributed modules from an earlier version of Drupal won't work with the latest version of Drupal. In other words, there is no backwards compatibility and you must upgrade all your contributed modules to the version that corresponds to the version of Drupal you are upgrading to.

So it is important to take an inventory of all the modules that you currently have installed in Drupal 5. The best way to do this is with a module called update status. Update Status lists all the modules installed on your site along with the version number and whether or not there are newer versions of those modules available for download. If you don't already have it installed I encourage you to do so, as it will make module upgrade planning (covered in the next section) much easier.

Write down all the modules you currently have installed so you have a list you can check off later in later steps. You will in fact use this checklist a number of times.

Several modules also have 'sub modules' or components that are enabled in Administer » Site Building » Modules (admin/build/modules). Since you are taking a module inventory at this stage, this is a good time to also write down every module and sub-module listed on the module administration page that is enabled (has a checkmark next to it). You will use this as a check list when you re-enable modules at one stage during your upgrade.

Before you do anything: Planning Part 2 - Research Module Upgrades

Now that you have an inventory of modules you can begin answering a few questions for each of them.

Are you even using the module?

You may have installed modules and never enabled them. If you aren't using them why bother upgrading them? Remove any module from your inventory that you aren't using and don't plan on using after the upgrade.

Is there a version available for Drupal 6?

The 'update status' module provides links directly to the 'project' pages for the modules on For each of your installed modules go to their project page on and see if there is a version listed for Drupal 6. If not read through the project page description as the module author may provide alternatives you can use instead.

Update James Forbes Keir left a comment and brought my attention to the "upgrade status" module. This is very similar to update status (in fact it depends on update status), that you could also install to help find the upgrade path for your particular modules.

Is there an upgrade path from the Drupal 5 version you currently have installed to the Drupal 6 version?

Several modules authors have released multiple versions of their modules (e.g. module_name 5.x-1.x and module_name 5.x-2.x) and in some cases only the 2.x version is upgradeable to module_name 6.x-x.x. Once again, follow the project links from the update status module and read the project pages. See if there are any special notes about the upgrade path from one version of Drupal to the next. If there are make note of them. You may be required to upgrade your Drupal 5 version before you even upgrade to Drupal 6. This is the sort of thing you will need to do in the "getting Drupal 5 upgrade ready" phase.

Does the Drupal 6 version introduce any dependencies on other modules

In some cases newer version of modules have new dependencies on other modules that they may not have had in the Drupal 5 version. The project pages usually list these dependencies. You will need to make note of these dependencies and be prepared to install them as part of the upgrade process later on.

Before you do anything: Document Your Plan

At the top of this post, I included a screen capture of the mind map that I used to plan the upgrade of this site.

That was my way of documenting things like:

  • the modules that I wasn't going to bother upgrading
  • to the modules that couldn't be upgraded - and what alternative choices I had
  • which modules required an upgrade before I even upgraded to Drupal 6
  • special upgrade instructions (if any) for each module
  • in what order I was going to do things
  • how I was going to test that things worked

It even includes the steps from Upgrade.txt that I mentioned at the beginning of this post. In short, I made a giant list of steps and checklists (broken into four phases) that I could refer to as I went through the upgrade process. There are too many things that are easily forgotten when doing an upgrade and having everything written down ahead of time is going to save you tons of time and aggravation.

Also, having a document like this ahead of time provides you with a place to take additional notes during the upgrade. Notes that may prove valuable the next time you have to do an upgrade.

Next Steps and Other Reading

In my next post I'll cover steps to take to get your site ready for upgrade after you have your plan.

If you have any additional planning tips or tools or experiences, leave a comment.

Update Follow up posts Step 2 and Step 3 and 4 of my How to Upgrade Drupal 5 to Drupal 6 series are now on-line

Here are some additional links to resources to help you plan your upgrade:

January 9th 2009 12AM
By: andre



Deleting files and directories

I am curious about the difference between:

#1 deleting files and directories and backing /files and /sites from the D5 version, unpacking D6 and restoring /files and /sites

...compared to

#2 unpacking D6 (excluding /files and /sites) and overwriting the D5 files and directories?

Is there an obvious reason to favor #1 over #2?

another page

I have a set of bash scripts that make updating easy. See

Custom Changes

Make sure to note and research all custom changes that were done. The first site I upgrade had minor modifications that I lost, so it is always in my planning steps now. Plan, plan, plan and then check your plan. The best advice I have read.


Really interesting use of the mindmap, wish I could see it though. So you use the mindmap to keep track of the modules you're using and your strategy plan. Do you use it after upgrade to keep track of bugs and other maintenance issues?

Yes and then No

Yes, I do use it to keep track of the modules. Yes I do use it to keep track of the 'strategy' (steps and sub steps that will require action during the process).

I keep the mindmap so I have documentation of 'how' the upgrade ran, but not for bug tracking and maintenance. However, if complex maintenance is required, I will build a new mindmap on how to execute the maintenance job.

FYI: Your link to the CVS

FYI: Your link to the CVS entry for UPGRADE.txt actually links to the CVS entry for update.php.

oops thanks

fixing that now.

Upgrade Status module

Worth looking at the Upgrade Status module too, which saves you having to manually go to each module project page:


I'll update the docs to include this.

Acquia upgrade document

Acquia has published a very good upgrade document (60 pages!) as a chapter in their Getting Stared Guide. You may want to add that to your resources list.

Thanks and done

I didn't know that document existed. Looks to be quite a thorough overview of upgrading. Quite similar to what I am writing here... which illustrates a good point about the Drupal universe, if you think it it already exists somewhere.