Installation & setup
Which Ubuntu or Debian version to install Koha on
The newest Ubuntu LTS or current Debian stable, and nothing else — here is the one command that confirms it before you build the server, and what each other choice actually costs.
Updated 2026-08-12 · Tested against Koha 26.05
Use the current Ubuntu LTS or the current Debian stable, 64-bit, and nothing else. Both are what the Koha community builds and tests packages against, and both give you years before the question comes up again. Before you install anything else on the server, confirm it in one command: apt-cache policy koha-common must show a candidate version.
Step 1Check before you build the server, not after
This takes two minutes on a fresh machine and saves rebuilding one. Add the repository, then ask apt whether a package exists for this release:
$ wget -qO- https://debian.koha-community.org/koha/gpg.asc \ | sudo gpg --dearmor -o /usr/share/keyrings/koha-keyring.gpg$ echo "deb [signed-by=/usr/share/keyrings/koha-keyring.gpg] \https://debian.koha-community.org/koha stable main" \ | sudo tee /etc/apt/sources.list.d/koha.list$ sudo apt update$ apt-cache policy koha-commonA candidate version and a version table means this release works. Candidate: (none), or an install that then reports unmet dependencies, means it does not — and the fixes for each are in apt cannot install koha-common.
Do the check in something disposable
What each choice actually costs
| Choice | What it costs you |
|---|---|
| <strong>Current Ubuntu LTS</strong> | Nothing. The most-used platform for Koha, five years of security updates, and the version most community answers assume. |
| <strong>Current Debian stable</strong> | Nothing, and slightly older packages by design — which is a virtue on a library server. Debian is what the packaging targets first. |
| <strong>The previous Ubuntu LTS</strong> | Usually works, but you will reach the day when the current Koha branch needs a newer Perl module than your release ships. Then it is oldstable, then it is a rebuild. |
| <strong>A non-LTS Ubuntu (25.10 and the like)</strong> | Nine months of support. You will be rebuilding the library's server inside a year, for no benefit. |
| <strong>Debian testing/unstable</strong> | Packages move under you without warning. A catalog is not the place. |
| <strong>RHEL, Rocky, AlmaLinux, openSUSE</strong> | There are no Koha packages. Everything below applies — a source install, and every koha-* command in every guide is missing. |
| <strong>Windows or macOS</strong> | Not a server platform for Koha at all — see can you install Koha on Windows? |
Why the distribution matters this much
Koha is a large Perl application, and the packaged install deliberately does not bundle its own Perl libraries. koha-common depends on your distribution's packages for them — dozens of them. That is the right decision for a server you have to keep patched for a decade: security updates for those libraries arrive through the same apt upgrade as everything else, instead of sitting frozen inside an application directory.
The price is that Koha can only be installed where the distribution happens to ship versions new enough for the release you are installing. That is not a policy the project chooses release by release; it is arithmetic, and it is why "supported" moves.
The second half of the answer is the koha-* commands. koha-create, koha-dump, koha-plack, koha-rebuild-zebra and the rest are Debian packaging, not part of Koha's Perl. They assume the Debian layout — instances under /etc/koha/sites/, logs under /var/log/koha/, Apache configured with a2ensite, services under systemd. On a distribution without the packages none of those exist, so every answer you find in the manual, on the mailing list or here has to be translated before it can be used. That, far more than getting Koha running once, is what makes a non-Debian install expensive.
If the server is already built on the wrong thing
Before the catalog goes live, rebuild. It is an afternoon, and every later problem gets easier.
Once it is live, do not upgrade the distribution underneath a running Koha in place. Build the new server beside it, restore a dump onto it, test it properly, and move the DNS — the same procedure as any migration, and the only one where a failure leaves the old catalog still working.
If the choice you are really weighing is packages against a source install rather than one distribution against another, that decision has its own consequences — and they last longer.
Would rather not do this yourself? We do it as a service — and if you would rather it were already done, it is on Koha Cloud before you log in.
Related
More on installation & setup
Answers to the questions that usually arrive with this one.
Koha packages or a source install: which one you want
Almost every library wants the packages. Here is exactly what a source install gives up — the koha-* commands, the upgrade path, and most published answers — and the two cases where it is still right.
apt cannot install koha-common
Unmet dependencies, NO_PUBKEY, or apt claiming the package does not exist. Four causes, in the order they actually occur, with the one command that tells you which of them you have.
Apache will not start: Invalid command 'RewriteEngine'
Apache refuses to start after enabling a Koha site because mod_rewrite is not enabled. One command fixes it — and the same class of error covers the other three modules Koha needs.
The Koha web installer returns a 500 error or times out
The installer dies partway through and the browser shows a 500 or a gateway timeout. Read the instance log to find out which step failed, then restart the install cleanly rather than retrying on a half-built database.

