Koha upgrade guide: how to upgrade an old Koha version without losing data

How the Koha release cycle works

Koha publishes two major (feature) releases a year, in May and November, on or around the 22nd of the month. Version numbers follow the year and month: 25.05 is the May 2025 release and 25.11 the November 2025 release. Between major releases, the community publishes monthly maintenance releases, such as 25.11.10, which bring only bug fixes and security patches.

The community maintains several branches at the same time and names them by relative age: stable is the newest, oldstable the previous one and oldoldstable the one two releases back. It generally supports two to three major versions for bug and security fixes, for an average of 18 months each. In addition, since version 22.11 there has been a long-term support (LTS) branch every two years, always in November, with extended maintenance of about three and a half years, designed for institutions that need prolonged stability. The official calendar is on the community's release schedule page.

This is the status of the branches in early November 2026, according to the community's release announcements and download server:

Koha 26.11 is scheduled for around November 22, 2026. When it is released, the stable, oldstable and oldoldstable labels shift accordingly, so check the current status at koha-community.org before choosing a target. As a practical rule, an instance that has gone three or four years without an upgrade is already out of maintenance.

The risks of staying on an old Koha version

• No security patches. Each maintenance release usually fixes real vulnerabilities, such as SQL injection, cross-site scripting or code execution in templates. Outside the maintained branches those patches never arrive, and the OPAC is a public service exposed to the internet.
• Expired operating-system dependencies. Koha runs on Debian or Ubuntu with Perl and MariaDB; if the operating system is also out of support, the problem is no longer only Koha's.
• Features that never arrive. Whole modules, OPAC accessibility improvements and REST API enhancements exist only in recent versions.
• The jump gets more expensive with time. Upgrading every six or twelve months is routine; doing it after four years is a project with testing, rework of customizations and retraining.
• Fewer people who can help. Community lists and providers work on current versions; on a discontinued version, answers are scarce.

What changes between major versions

These milestones explain why the jump is so noticeable when an instance has been dragging several years behind. The list is not exhaustive, since each major release brings hundreds of fixes and dozens of enhancements, but it helps anticipate what will change on screen and in daily operations:

Of all these, the move to Bootstrap 5 creates the most work during an upgrade. If your OPAC has custom CSS written for earlier versions, some alignment and spacing classes changed names and will stop applying. It is not a serious problem, but it is real work that must be included in the quote.

The safe route for jumping several versions

Do not leap from a very old version to the current one in a single blind step: each major release added its own schema updates, and all of them must be applied in order. The proven route is:

1. Clone production to a test server: full database, configuration files, templates and custom CSS.
2. Record the starting point: exact Koha version, operating-system version, MariaDB or MySQL version, the search engine in use and the list of installed plugins.
3. Upgrade the operating system if it is also out of support. A four-year-old Koha commonly runs on a Debian release that no longer receives patches.
4. Move up branch by branch, letting Koha apply the schema updates at each step and checking that the instance starts before continuing.
5. Rebuild the search indexes once you reach the target version.
6. Review customizations: OPAC CSS, modified templates, plugins, notices and saved SQL reports.
7. Test real workflows with library staff: catalog, check out, check in, place a hold, renew, run the month-end report.
8. Schedule the production window outside academic hours, with a backup taken immediately before and a rollback plan.

How a Koha upgrade updates the database schema

This is the part that causes the most anxiety and, paradoxically, the most automated one. When the new version is installed, Koha detects the version recorded in the database and runs the pending updates in sequence. In large catalogs this can take from a few minutes to more than an hour, because some updates rewrite entire tables.

Three precautions are non-negotiable: take a full database dump immediately before starting, check that there is enough free disk space for the temporary growth of tables, and never interrupt the process halfway. If something fails, restore the dump and start again. That is why a rehearsal on a clone is the difference between a controlled incident and an emergency.

What breaks: plugins, templates and CSS

Koha's core migrates well. What needs review is everything built on top of it:

• Plugins: each one declares which Koha versions it supports. An unmaintained plugin may be left behind, and you must decide whether to replace, adapt or drop it.
• Templates edited directly: if someone edited the OPAC template files on the server, those changes are lost on upgrade. The right fix is to reimplement them with the customization preferences Koha itself provides.
• OPAC CSS: the critical point of the jump to Bootstrap 5. Check alignment, spacing and float classes.
• Saved SQL reports: they query tables directly. If a version changed a table's structure, the report stops working or, worse, returns wrong figures without warning. Revalidate them one by one.
• Integrations: LDAP or SAML authentication, SIP2 self-check, OAI-PMH harvesting and any consumer of the REST API must be tested explicitly.
• Notices and email templates: overdue and hold-available messages may need adjustments if the available variables changed.

Training after the upgrade

If the instance predates the staff interface redesign, your team will find a different system on Monday morning. The logic of cataloging and circulation is the same, but navigation, menus and the location of several actions change. In BiblioLabTech's upgrade projects this is solved with one or two short sessions per area (cataloging, circulation, acquisitions), backed by an internal guide with screenshots of the upgraded system rather than the generic manual. Also reserve the first two weeks after the upgrade for reinforced support: most tickets in that period are not failures but questions about where an option went.

Pre-upgrade checklist

• A full database dump, verified and restored at least once in the test environment.
• A copy of configuration files, templates and custom CSS.
• An inventory of plugins with their versions and declared compatibility.
• A list of saved SQL reports that must be revalidated.
• A decided target version: recent stable or LTS, depending on the institution's tolerance for change.
• A maintenance window agreed with the library, outside exam and enrollment periods.
• A written rollback plan: under what conditions to abort and how long a restore takes.
• Someone responsible for telling users that the OPAC will be offline during the window.

Upgrading Koha with BiblioLabTech

The production window usually lasts a few hours, but the whole project includes cloning the environment, rehearsing the jump, reviewing customizations and testing with staff. For an instance several versions behind, plan on two to four weeks of work before the cutover window. BiblioLabTech tests each upgrade in a staging environment, verifies custom templates and integrations, and then upgrades production in an agreed maintenance window, whether your library implemented Koha with us or with another provider. Planned upgrades are part of our annual Koha support services, and libraries that implement Koha with BiblioLabTech also receive BiblioScan AI cataloging at no extra cost.

If your instance has gone years without an upgrade and also lives on a server nobody maintains, the upgrade is the natural moment to rethink the infrastructure: see Koha hosting: managed cloud or your own server. If the catalog also carries duplicates and records without items, combine the upgrade with a cleanup, as described in how to migrate to Koha. For the full picture of the platform, see the Koha implementation guide. To have us do it, visit our Koha service or send us your current version.