Installation & setup
Can you install Koha on Windows? (WSL2, VMs, and when not to)
There is no Windows build of Koha. You can run it on a Windows machine through WSL2 or a virtual machine — which is fine for evaluation and wrong for a live library.
Updated 2026-08-09 · Tested against Koha 26.05
There is no Windows version of Koha. It is distributed as Debian and Ubuntu packages and expects a Linux system underneath. You can run it on a Windows machine through WSL2 or a virtual machine, and that is a good way to evaluate it — but a library that will actually circulate books should run Koha on a Linux server.
Evaluating, or going live?
- Evaluating — WSL2 on your own laptop is the fastest route, and free.
- Training or a demo — a virtual machine you can snapshot and reset.
- A live library — Ubuntu LTS on a server or a hosted machine. Not Windows, not WSL2.
WSL2 — the practical way to try it on Windows
Windows Subsystem for Linux runs a real Ubuntu kernel on your Windows machine. Koha installs into it exactly as it would on a server, with no changes to the procedure.
$ wsl --install -d Ubuntu-24.04Reboot when it asks, set a username and password when Ubuntu first starts, then follow the ordinary installation — installing Koha on Ubuntu applies from that point without modification. Reach the OPAC from Windows at http://localhost and the staff interface at http://localhost:8080.
Two WSL2 details that waste an afternoon
- Services do not start on boot. WSL2 does not run systemd the way a server does, so after a restart you may need
sudo service apache2 startandsudo service mysql startby hand. - Hostname-based virtual hosts need a hosts-file entry. Add the names you configured to
C:\Windows\System32\drivers\etc\hosts, or stay onlocalhostand ports.
A virtual machine — better for training and demos
VirtualBox, VMware or Hyper-V running Ubuntu Server gives you something closer to the real thing: proper systemd, its own network address, and — the part that matters for training — snapshots. Take one after installing, let a class break everything, and restore it in seconds.
Give it 4 GB of RAM and 20 GB of disk for a small test catalogue. Use bridged networking if other machines on the network need to reach it.
Why not for a live library
None of the reasons are that Koha would not run. It runs. The reasons are operational, and they all arrive on the same day.
- It does not come back by itself. A Windows desktop reboots for updates; WSL2 does not restart Koha's services afterwards, so the library opens to a catalogue that is down and nobody knows why.
- Backups are a manual habit. The nightly
koha-run-backupsjob runs from cron, and cron on a machine that is switched off at night does not run. - Nobody else supports it. Every guide, every mailing-list answer and every consultant assumes a Linux server. Under WSL2 you are debugging your platform as well as your problem.
- It is a desktop. A staff PC gets shut down, unplugged, reimaged and replaced, and the catalogue for the whole library is on it.
The honest version: WSL2 is excellent for learning Koha and unsuitable for depending on it. Evaluate on Windows, and move to a Linux server — a small cloud instance or one machine in a cupboard — before the first patron record goes in.
What to run instead
Ubuntu Server LTS or Debian stable, on hardware or a cloud instance you can leave switched on. Koha is not demanding: a small library runs comfortably on 2 CPUs and 4 GB of RAM, and the whole installation is a package install plus one koha-create.
If the reason Windows came up is that nobody at the library administers Linux, that is a real constraint and worth naming rather than working around. The choices are to have someone run the server, or to have it run for you — which is what Koha Cloud is. Either is better than a production catalogue on a desktop.
Common WSL2 problems
| What you see | What it usually is |
|---|---|
| <code>localhost</code> refuses the connection | Apache is not running. WSL2 does not start it after a restart — sudo service apache2 start. |
| Port 8080 does not answer | Apache is not listening on it — see Koha, Apache and port 8080. |
| MySQL will not start | sudo service mysql start. Under WSL2 systemctl often is not the right command. |
| Cron jobs never run | Cron is not started, and the machine is off overnight anyway. Both are why this is not a production setup — see Koha cron jobs. |
| Very slow file access | The files are on the Windows drive under /mnt/c. Keep everything inside the Linux filesystem. |
| Cannot reach it from another computer | WSL2 is behind a NAT. Use a virtual machine with bridged networking instead. |
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.
MySQL or MariaDB for Koha, and which version
Install MariaDB from your distribution's own repository. Both work — Koha depends on a virtual package that either satisfies — but one of them is what everybody else is running.
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.
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.
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.