Installation & setup
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.
Updated 2026-08-09 · Tested against Koha 26.05
Koha has no default admin password. One is generated when the instance is created and written to that instance's configuration file. Print it on the server with sudo koha-passwd <instance>. This is the account the web installer asks for on first run — not a librarian account, and not something to hand to staff.
$ sudo koha-passwd library Username for library: koha_libraryPassword for library: X7fQ2mB9kLpRReplace library with your instance name; sudo koha-list prints the instances on the box. Run interactively, the command pauses and clears the screen afterwards, which is deliberate — it is trying not to leave the password in your scrollback.
What that account actually is
The username is almost always koha_<instance>, and it is the database user from /etc/koha/sites/<instance>/koha-conf.xml. Koha treats it as a superlibrarian at the staff login so there is a way in before any human account exists.
Use it once, then stop using it
- Use it to complete the web installer and create the first real superlibrarian.
- Give every human their own staff account with the permissions their job needs.
- Never share it with library staff, and never use it for day-to-day work.
Resetting a staff account instead
If a librarian is locked out, the answer is not this account. Reset theirs directly, and Koha prints the new password:
$ sudo koha-reset-passwd library jsmith The password has been changed to: T4vN8sQ1wZxEThe second argument is the userid from the patron record, not the surname and not the card number. Give them the new password and have them change it at My account → Change password on first login.
A superlibrarian can do the same from the staff interface — Patrons → find the staff member → Change password. Use the command line only when nobody can log in at all.
You do not know the instance name
$ sudo koha-list librarytrainingNo output means there are no instances on this server — the package is installed but koha-create was never run, so there is nothing to have a password for.
Why there is no default password
A published default is a password that is live on every install until somebody changes it, and on a fresh Koha the staff interface is reachable before anyone has had a reason to change anything. Generating one per instance means the window where a known credential works does not exist.
It also means the password is never in your notes, your ticket system or a guide — it is only on the server, readable only by root. That is a mild inconvenience once and a genuine protection permanently, which is the right trade for the account that can do everything.
When it still will not log in
| What you see | What it usually is |
|---|---|
| <code>Unknown instance</code> | The instance name is wrong. Check sudo koha-list — it is the name, not the hostname or the database name. |
| Password prints but is rejected | You are on the OPAC login, not the staff interface. The staff site is a different port or hostname — see Koha, Apache and port 8080. |
| Login page never appears | Apache is not serving the staff virtual host. sudo a2ensite library, then reload Apache. |
| Logs in, then immediately logs out | Session storage is broken — usually memcached configured but not running. Check systemctl status memcached. |
| <code>command not found</code> | You are inside koha-shell, or this is a git install. The koha-* commands come from the koha-common package and run as root on the host. |
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.
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.
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.