Koha upgrades are routine — if you have a backup you have actually restored and a staging copy to try the upgrade on first. Without those two things, an upgrade is a gamble with your catalog.
This guide covers the safe sequence, what breaks most often, and how to get back if it goes wrong.
Koha's release cycle
Koha publishes two major releases a year, with maintenance releases in between carrying bug and security fixes. Each major release is supported for a defined period, after which it stops receiving fixes — including security fixes.
Check the current schedule and support windows on the Koha community site before planning; they are published and they do shift.
Why falling behind gets expensive
Upgrades compound. Database updates run in sequence, so moving from a version four releases old runs four sets of changes in one go, with four releases' worth of behaviour changes landing at once.
Worse, the further behind you are, the less anyone remembers about how your installation was set up — and the more likely it is that whoever configured it has moved on. Upgrading regularly is easier than upgrading eventually.
Before you upgrade
- Take a full backup and restore it somewhere. Not just take one. See our backup guide.
- Write down your current version. You need it to roll back and to read the right release notes.
- Inventory your customizations — system preferences you changed, custom CSS and JS, plugins, frameworks, custom reports. See our customization guide.
- Read the release notes for every version between yours and the target, not just the target.
- Pick a low-traffic window and tell staff in advance.
Upgrade on a staging copy first
The step that turns an upgrade from a risk into a rehearsal, and the one most often skipped for lack of time.
Build a copy: a separate server or virtual machine, restore your database and files, confirm it works, then upgrade that. Test at minimum: check out an item, check it in, place and fulfil a hold, generate a notice, run your most-used reports, load the OPAC and search, and confirm your branding still applies.
Leave the staging copy up for a few days and let a cataloger and a circulation assistant use it. They will find things a checklist does not.
Running the upgrade
Update the package, then run the database upgrade step and watch it. Do not start it and walk away. Errors during the database update are the ones you need to see as they happen, because continuing past one compounds the problem.
Afterwards, restart the services — including the SIP2 daemon if you run one, which is frequently forgotten and results in dead self-check units the next morning.
After the upgrade — what to re-check
Most "the upgrade broke things" reports are one of these six. Work through them every time:
- Cron jobs — still scheduled and still running. See our cron guide.
- Notices — send a test and confirm it arrives. See notices not sending.
- Z39.50 targets — run a copy-cataloging search.
- Custom CSS and JS — still present and still applying.
- Custom reports — SQL that referenced a changed column will now fail.
- OPAC appearance — load it as a patron would, on a phone as well.
What usually breaks
- Template customizations overwritten. Anything that modified Koha's own templates is replaced by the new version. This is the upgrade cost of climbing the customization ladder.
- Plugins incompatible with the new release. Check before upgrading, not after.
- System preference defaults changed. New preferences arrive with defaults that may not match your policy. Release notes list these.
- Report SQL failing because a column was renamed or removed.
- SIP2 not restarted — self-check units dead, Koha fine.
- Search index needing a rebuild — searches return nothing, which looks catastrophic and is not.
How to roll back
Decide this before you start, because deciding it afterwards is much harder.
Rolling back means restoring the previous database and downgrading the package — Koha's database upgrades are not reversible, so the backup is the only route. This is precisely why the restore has to be tested beforehand.
Set a time limit in advance: if the upgrade is not working after a defined number of hours, roll back and try again another day. Libraries get into trouble by pushing on at 11pm.
How often should you upgrade?
For a library with dedicated technical staff: every major release, one release behind the newest, so the first wave of bug reports has already been fixed.
For a library without: at minimum, stay within the supported window so you keep receiving security fixes. Falling out of support is the genuinely risky position.
That said — look back at what this article has asked of you. A staging copy, a tested restore, a rehearsal, a watched upgrade, six things to re-check, and a rollback plan. Twice a year. Forever.
It is entirely doable with staff time allocated to it. Where that time does not exist, the honest alternative is not skipping upgrades — it is not owning them. On Koha Cloud upgrades happen continuously and are tested before they reach your library: there is no window to schedule, no staging copy to build, and the six checks above are checks we run. Upgrades handled for you, so your staff spend the day on the collection instead.
Several versions behind and nervous about it? We do Koha upgrades, including large jumps from long-unmaintained installations. We upgrade a copy first and show you it works before touching your live system.