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.
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.
Koha cannot locate the configuration file koha-conf.xml
The error means the process has no KOHA_CONF set, not that the file is gone. Run the command through koha-shell, and here is how to confirm the file really is where Koha expects it.
Koha, Apache and port 8080: staff and OPAC on two hostnames
Koha serves two websites from one install. Here is how the OPAC and the staff interface are separated, why staff lands on port 8080, and how to move it off.
Finding your Koha instance’s admin password (koha-passwd)
The credentials the Koha web installer asks for are generated at install time and printed by koha-passwd. Here is how to find them, and how to reset a staff login.