Koha System

How to Reset the Koha Admin Password

Step-by-step guide to resetting any Koha patron or admin password using koha-reset-passwd. Covers the correct command, common errors, and the workaround for a known upstream Koha bug affecting package installs.

May 27, 2026 4 min read

This guide explains how to reset the password for any Koha patron or staff account from the command line. This is the correct method when you are locked out of the Koha staff interface, when an admin or patron account password has been forgotten, or when you need to regain access during initial setup.

Understanding Koha Password Commands

Koha ships with two password-related commands that are easy to confuse:

Command	What it does
`koha-passwd <instance>`	Reads the MySQL database user password for the Koha instance. Used during initial web installer setup. Does not reset staff login credentials.
`koha-reset-passwd <instance> <userid>`	Resets the Koha login password for any patron or staff account. Generates a new random password and prints it. Also accepts `--patron_id` (borrowernumber) or `--cardnumber` instead of userid.

To reset a staff login, you need koha-reset-passwd.

Step 1: Connect to Your Instance

Connect to your EC2 instance. The recommended method is SSM Session Manager — no open ports or key pairs required.

Via AWS Console:

Go to EC2 → Instances
Select your instance
Click Connect → Session Manager → Connect

Via AWS CLI:

aws ssm start-session --target i-YOUR_INSTANCE_ID --region us-east-1

See How to Connect to Your Koha EC2 Server for full details.

Step 2: Find the Account Username

If you are not sure what username was used during setup, query the database. Staff and admin accounts have a non-null flags value; regular patrons have NULL:

sudo koha-mysql library -e "SELECT userid, borrowernumber, flags FROM borrowers WHERE flags IS NOT NULL AND flags > 0;"

Example output:

userid          borrowernumber  flags
demo            51              1

flags = 1 means superlibrarian (full admin access). The username is whatever was set during the Koha web installer — there is no fixed default. Use the query above to find it.

Step 3: Reset the Password

Run koha-reset-passwd with the instance name and the username (replace demo with the userid from Step 2):

sudo koha-reset-passwd library demo

The command prints a new randomly generated password:

demo Xk9mT2vLqR8pNw3j

Save this password immediately — it is only shown once. Then log in to the Koha staff interface with this new credential.

Common Error: `env: '/bin/admin/set_password.pl': No such file or directory`

If you see this error when running koha-reset-passwd:

env: '/bin/admin/set_password.pl': No such file or directory

This is a known upstream Koha bug affecting all package installs. The wrapper script koha-reset-passwd is missing a line that loads the Koha environment before calling the underlying Perl script, so the path resolves incorrectly.

All KohaSupport AMIs built after 27 May 2026 include the fix automatically. If your instance was launched before that date, apply the workaround below.

Workaround

Run the password reset through koha-shell, which loads the correct Perl environment:

sudo koha-shell library -c "/usr/share/koha/bin/admin/set_password.pl --userid demo"

Replace demo with the actual userid from Step 2.

Note: This is a confirmed upstream bug in the Koha package scripts. KohaSupport is working on a fix and will publish the patch upstream soon. All KohaSupport AMIs built after 27 May 2026 include the fix automatically.

Retrieving the Database (Master) Password

koha-reset-passwd resets staff/patron login passwords — it does not retrieve or change the MySQL database user password. For information on finding the database username and password stored in koha-conf.xml, see How to Retrieve the Koha Database Username and Password.

Frequently Asked Questions

Can I set a specific password instead of a random one?

koha-reset-passwd always generates a random password. To set a specific password, use the Koha staff interface:

Staff interface → Administration → Patrons → find user → Edit → change password
Or use the Perl script directly: sudo koha-shell library -c "/usr/share/koha/bin/admin/set_password.pl --userid demo --password 'YourNewPassword'"

I reset the password but still can’t log in.

Check:

You are logging in to the staff interface (default port 8443 or staff.yourdomain.com), not the OPAC
The username is exactly as returned by koha-reset-passwd (case-sensitive)
Wait 10–15 seconds after reset — Koha caches sessions

What is the default username?

There is no fixed default. The superlibrarian username is set by whoever completed the Koha web installer. Use the SQL query in Step 2 to find it.