I'm embarrassed to post this but have to ask!

My understanding of how to upgrade a module is: (Question marks are things I'm not sure about.)

1) Download the latest version.
2) Unzip it.
2.5) Disable old module through admin panel?
3) Delete the old module + folder.
4) Replace old with new on server.
5) Run update.php to update the database?

I'm a little confused about update.php. I run multiple sites with separate databases off of a single code base. Do I need to run update.php for each database? If so, can I get away with just typing in the domain name and update.php or do I need to physically move a copy into the site directory? And finally, how do I know if I need to run update.php or not?

I couldn't find anything searching that dealt just with updating a module though it must be somewhere around here... Sorry if this post is redundant...


NancyDru’s picture

You will need to run update.php on each database that supports that module.

I'm not sure what you mean "do I need to physically move a copy into the site directory?" If the module is used by all sites, it should be in sites/all/modules; if it is only used by one or two sites, it should probably be in the sites/domainname.com/modules directory. But update.php itself is core Drupal so it is available to all sites.

A basic rule of thumb is that if you replace a module, run update.php. Regardless of the warning that shows up, I have never seen a problem with running it when it wasn't really needed. But you will certainly see problems if you don't when you should.

Nancy W.
Drupal Cookbook (for New Drupallers)
Adding Hidden Design or How To notes in your database

wisdom’s picture

Yes you need to unzip and save the new module files to the site directory replacing the old module files. This action only copies file but does not do any change on the databae. If the new module has a database modification that is for what update.php is for, yes you could run the update.php script to automatically update the database structure.

The update.php calls the hook_update function in module.install file to perform the necessary update. For example, you can find hook_update in system.install of the core module, system.module.

However, all modules may not have hook_update. Because this is something which is added if the state of development of the module requires an update of the database definition like dropping or adding columns, etc. To make sure your module has hook_update, in easy way, when you clike update.php
you will get a list of modules with updates. If your module has updates it will be listed there.

The module you are working if it is not in the list, you could change the database structure manually or include the update script in the module.install file or simply delete the old table and reinstall.

Online Business

yolene’s picture

now here is a tricky question :
i installed a newer version of a module (views) and it broke my website (actually only some views) and i don't have a backup of the database (i didn't suspect that using my webhoster's backup function would mean backup only files and not database ... ooops).

So i need to roll back to the previous version of the module ... how do i do that ?
Is this correct :
_erase the folder with new version
_import the folder with old version
_run update.php without changing any values there
Thanks in advance for your advice.

NancyDru’s picture

You should not run update.php, although it shouldn't hurt. If the new version had an update, you will need to manually undo it, and reset the system table schema column.

Korak1’s picture

Just want to say thanks for responding to my question. I appreciate it!

Jkello’s picture


Just want to confirm. Do I need to disable it in my admin panel?

I am using Drupal 6

NancyDru’s picture

If the new module changes the menu or theme functions, you will either need to disable/enable it or clear the caches (admin>performance). I, as a developer, personally find it better ("cleaner") to go the disable/enable route.

Nancy W.
Drupal Cookbook (for New Drupallers)
Adding Hidden Design or How To notes in your database

chrisdfeld’s picture

Assuming you were to follow the steps above:

1) Download the latest version.
2) Unzip it.
2.5) Disable old module through admin panel
3) Delete the old module + folder.
4) Replace old with new on server.
5) Run update.php to update the database

When should you re-enable the module -- before or after running update.php? In other words, would "Re-enable new module" be step 4.5 or 6 above?

Along those lines, does running update.php make any changes on behalf of modules that are installed but not enabled, or are modules ignored during update unless they are active?

Thanks for any advice. I agree that this process needs more clarification, especially considering the alarmist warnings on Drupal screens about the utter necessity of running update.php and the risk of running it too many times.

NancyDru’s picture

Answering your second question first: if a module is not enabled then its updates are not even looked at; they will not be in the update list.

So that means re-enabling would have to be 4.5. In actuality, one must be careful about disabling modules at all to upgrade. In some cases, important associations can be lost. For example, for node modules, the association to the content type in a vocabulary will be lost. I personally recommend that you not disable the module before upgrading (unless you are doing something like a 5 to 6 upgrade).

NancyDru (formerly Nancy W. until I got married to Drupal)

mobabo’s picture

This thread may be useful to people trying to upgrade modules: http://drupal.org/node/288594#comment-941253

chrisdfeld’s picture

I see your point about how disabling modules can cause issues in some cases. However, I noticed you had a more nuanced approach in your earlier post above.

So, to confirm, you would recommend the following?

Upgrading modules while doing a major Drupal version upgrade (e.g. Drupal 5 to 6):

1) Download the latest version.
2) Unzip it.
2.5) Disable old module through admin panel
3) Delete the old module + folder.
4) Replace old with new on server.
4.5) Re-enable the new module through admin panel
5) Run update.php to update the database

vs. Upgrading modules when not upgrading Drupal:

1) Download the latest version.
2) Unzip it.
(do not disable the old module)
3) Delete the old module + folder.
4) Replace old with new on server.
5) Run update.php to update the database

Thanks again.

omnyx’s picture

so what's the deal - disable or do not disable when doing module updates within the same Drupal core version (i.e 5.x) ?

NancyDru’s picture

drupypal’s picture

This is a great thread and very informative. For some reason when searching the site I had a bit of trouble finding this so in my first several attempts. I thought to add a few key words to make life easier for future searchers.

installing new modules over old modules
upgrading modules
how to upgrade a module

Nico_O’s picture

I believe the module should be disabled before removing the old files and putting in the new. And the module should be enabled again before running update.php.

Otherwise there can be issues if there are changed dependencies.

mtpultz’s picture

Don't some of the modules remove table when removed. Wouldn't it be better to just pull out and replace then update so you don't lose any data? I'm at the same spot as above which one do I do... steps 1-5 group A or steps 1-5 group B?

WorldFallz’s picture

Disabling a module does not uninstall it. Uninstalling a module will usually lose it's data and settings, disabling it is harmless. I use cvs for updates and never bother disabling modules for non-major version updates. Also, you should also read the release notes and see if there are any special instructions or info about the changes before doing an update.

Most importantly-- as always, you should always make a backup before doing anything to your site.

cloneofsnake’s picture

This is excellent info on updating modules! Thanks.

eff_shaped’s picture

I appreciate your summary and pursuit of clarity. The confused among us certainly need it.

clivesj’s picture

NancyDru (formerly Nancy W. until I got married to Drupal)

arnoldc’s picture

I am surprised that I have to resort to this thread in order to learn how to upgrade a module. At least I found the information now. Thanks guys.

NancyDru’s picture

Feel free to compose a handbook page to clarify it to others.

rkarajgi’s picture

I agree that this issue of upgrading needs some more documentation. IMHO, it is bit cryptic from new Drupal users' point of view and all references point to upgrade.txt again and again - which is not very elaborate.

My understanding is as follows - there are two areas to be upgraded - code and database. If it is only code change, then upgrade is a piece of cake. Just drop new code, it all works flawlessly. But changes to database involve many issues.

IMHO, when it comes to changes to database, one has to worry about old table structure, new table structure, old-data etc. The upgrade.php is supposed to do this task. But the numbers associated with the upgrade are not well understood by user of upgrade.php. Those numbers should probably be not some serial numbers (1, 2, 3, 4) but show something like 5.1x-3.1 ==> 5.1x-3.4. That will make upgrade.php more usable and friendly. Module writers usually assume upgrade from previous state, but previous state could be 5 steps back.

Installing/Enabling/Disabling/Unstalling modules : The underlying implications of presence or absence of module's install file and the hook implementations can decide the right outcome. Some modules have implemented all this thoroughly but some have not. From long term use/upgrade/support point of view, imho, this is very important. Most long-time drupalers have probably learnt to read the module's install file, if any and figure out the right strategy. This results into one tending not to upgrade to new versions if it is not clear the upgrade will really work.

Maybe my understanding is flawed - but this is what I usually do:

>> Upgrading modules (e.g. from say "5.1x-3.1.tar.gz" to say "5.1x-3.4.tar.gz")
- this is usually very seamless and super quick
- disabling / uninstalling old modules is usually not needed
- usually modules do not change database schema much in such releases
- just add new tar file in same directory, just expand it. It automatically overwrites the old files.
- if module has a database file, usually some error shows up, then run the update.php - with trial and error one reaches the destination

>> Upgrading Drupal from 5.1 to 5.10
- I understand one can directly add Drupal 5.10 code into Drupal 5.1
- update.php has to be run to upgrade one step at a time to reach from 5.1 to 5.2 to ..... 5.10

- Rajeev Karajgikar, Drupaler in South Bay Area

- R Karajgikar

NancyDru’s picture

First, Update.php should be able to take you from 5.1 to 5.10 all at once - it did for me.

Especially when you get to 6.x, I recommend running update.php even if there are no database updates because there could be menu or theme changes that won't show up unless you clear the cache (yes, even if page caching is not enabled). Update.php will do that.

Uninstalling modules should only be done when you won't be using it again. Uninstall code should delete any nodes and variables the module created. This is recoverable only by restoring a database back up. I would never suggest it on an upgrade, not even major core upgrades. In some cases it is a good idea to delete the old code before untarring the new one because of changes in module files. I rarely even do this.

When updating, always keep careful track of what happens so you can report any anomaly in an issue. Don't forget to record your settings too.

denso’s picture

How do you "run" Update.php?

pedrosp’s picture

You just need to write on your browser : http://www.example.com/update.php (where "example" is your website of course)
Then press enter or click to "visit", the script will then "run".
Click on the link: run the database upgrade script
You will see another screen and you will need to press the "update" button.

NancyDru’s picture

On the modules admin page there is a link for it at the top of the page.

NancyDru (formerly Nancy W. until I got married to Drupal)

davidjmcq’s picture

Thank you for this very lucid comment.. the best I've found on this subject so far, and not at all complicated.

One thing though. What happens if a client accesses the site after I delete the old code, but before I copy in the new code, or before I run update.php? Should I have put the site in maintenance mode first?

If the client accesses the site before I run update.php but on the new code, can that potentially damage the database?

NancyDru’s picture

It depends on how busy the site is and how lucky you feel. I've never had a problem with this. However, yes, to be technically correct, put the site in maintenance mode first.

Generally you will likely only see database errors about missing or misnamed columns. There is a very small potential for messing up the database because most errors will result in the new data not being written. The only case I can think of where it might be a problem is when a column's format changes, for example from 'int(11)' to 'datetime'.

mjk3r’s picture

Website was handed over to me by somebody else. No updates were installed for more than a year...

Here is an example:
Content Construction Kit (CCK) 6.x-2.1
Recommended version: 6.x-2.8 (2010-Aug-12)
Security update: 6.x-2.8 (2010-Aug-12)
Security update: 6.x-2.7 (2010-Jun-16)
Security update: 6.x-2.2 (2009-Mar-19)

My question is - do I need to go step by step starting from the oldest (6.x-2.2, and each time run update.php)?

Or can I just go with the latest 6.x-2.8 and skip the rest?


NancyDru’s picture

You should be able to jump to the latest. Hook_update_N's should accumulate.

kbrinner’s picture

I know this is an old thread, but it came up first for me when I searched for upgrade Drupal module - there is more recent Drupal documentation in terms of how to upgrade modules here: http://drupal.org/node/672472. Hope others find it useful (as I did).