Install Koha on Ubuntu 24.04: Step-by-Step Guide (2026)

Installing Koha for the first time can look difficult. You need to work with Ubuntu, Apache, MariaDB, domain names, and several Koha commands. However, the process becomes much easier when you complete one step at a time.

In this guide, you will learn how to complete a manual Koha installation on Ubuntu 24.04 LTS. We will install Koha from its official package repository and configure the staff interface, OPAC, database, firewall, HTTPS, Plack, and backups.

This manual method is useful because it allows you to see what is happening at every stage. If you want a faster option, read our guide on automated Koha installation on Ubuntu using the script method.

If you are completely new to the software, our Koha Integrated Library Management System beginner’s guide explains what Koha is and how libraries use it.

What Is Koha?

Koha is a free and open-source integrated library system. Schools, colleges, universities, public libraries, and other institutions use it to manage their daily library work.

Koha can be used for:

• Cataloguing books and other materials
• Registering library members
• Issuing and returning books
• Managing renewals and reservations
• Calculating fines
• Managing serials and acquisitions
• Creating library reports
• Providing an online public catalogue

Koha has two main web interfaces.

The OPAC is the public catalogue. Library members use it to search for books, check their accounts, and place holds.

The staff interface is used by librarians. It provides access to circulation, cataloguing, reports, administration, and other management tools.

Why Install Koha on Ubuntu 24.04 LTS?

Ubuntu 24.04 is a Long-Term Support release. It is a better choice for a production server than an interim Ubuntu release because it receives security and maintenance updates for a longer period.

The Koha community also provides packages for modern Debian-based operating systems. Installing Koha through its package repository is easier to maintain than downloading the source code and building the software manually.

At the time of updating this guide, Koha 26.05 is the current stable branch. Koha 25.11 is also available as a version-specific branch. You can check the currently available versions in the official Koha package repository.

This guide uses the stable repository so that APT can install the current stable release.

Requirements for Installing Koha

Before you begin, make sure you have:

• Ubuntu Server 24.04 LTS
• Root access or a user with sudo permission
• At least 2 GB of RAM for learning or testing
• At least 4 GB of RAM for a small working library
• At least 20 GB of free storage
• A stable internet connection
• A static IP address
• SSH access
• A domain or subdomain for online access

More resources may be needed if your library has a large catalogue, many users, uploaded files, or several staff members working at the same time.

In this guide, we will use the following examples:

• Koha instance name: library
• OPAC address: library.example.com
• Staff address: library-intra.example.com

You must replace example.com with your real domain.

Step 1: Update Ubuntu

Connect to your Ubuntu server through SSH. Start by updating the package list:

sudo apt update

Install the available updates:

sudo apt full-upgrade -y

If Ubuntu installs a new kernel, restart the server:

sudo reboot

Wait for the server to restart and then connect through SSH again.

Step 2: Install Apache and MariaDB

Koha needs a web server and a database server. Apache handles the web pages, while MariaDB stores the library’s records and settings.

Install the required packages:

sudo apt install -y \
  apache2 \
  mariadb-server \
  ca-certificates \
  wget \
  gnupg \
  lsb-release \
  ufw

Start Apache and MariaDB:

sudo systemctl enable --now apache2 mariadb

Check Apache:

sudo systemctl status apache2

Check MariaDB:

sudo systemctl status mariadb

If both services show active (running), you can continue. Press q to leave the status screen.

Step 3: Add the Official Koha Repository

Koha is not installed from Ubuntu’s normal repository. We must first add the official Koha package source.

Download and save its signing key:

wget -qO- https://debian.koha-community.org/koha/gpg.asc \
  | gpg --dearmor \
  | sudo tee /usr/share/keyrings/koha-archive-keyring.gpg >/dev/null

Now add the stable Koha repository:

echo "deb [signed-by=/usr/share/keyrings/koha-archive-keyring.gpg] https://debian.koha-community.org/koha stable main" \
  | sudo tee /etc/apt/sources.list.d/koha.list

Update the package list again:

sudo apt update

Check which Koha version is available:

apt-cache policy koha-common

The candidate version shown in the output is the version APT will install.

Installing a Specific Koha Version

If your library specifically needs Koha 25.11, use the version-specific repository instead:

echo "deb [signed-by=/usr/share/keyrings/koha-archive-keyring.gpg] https://debian.koha-community.org/koha 25.11 main" \
  | sudo tee /etc/apt/sources.list.d/koha.list

Then update the package list:

sudo apt update

A specific version may be required when an existing library is testing an upgrade or using integrations that have not yet been checked with the newest release. New installations can normally use the stable branch.

Step 4: Install Koha

Install the main Koha package:

sudo apt install -y koha-common

This package includes Koha and the commands needed to create and manage Koha instances.

You do not need to install a separate package called koha-web for the standard package installation.

Verify the installed package:

apt-cache policy koha-common

Step 5: Secure MariaDB

Run MariaDB’s security tool:

sudo mariadb-secure-installation

The questions may differ slightly depending on your MariaDB version. You may be asked to:

• Use socket authentication
• Set or change the root password
• Remove anonymous users
• Block remote root login
• Delete the test database
• Reload the privilege tables

Read each question before entering your answer.

You do not need to create a Koha database manually. The koha-create command will create the database, database user, password, and configuration for the new instance.

Step 6: Configure Koha Site Names

Open the Koha sites configuration file:

sudo nano /etc/koha/koha-sites.conf

Find the domain and port settings. Change them to match your domain:

DOMAIN=".example.com"
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra"
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""

With these settings and an instance named library, Koha will use:

library.example.com
library-intra.example.com

The first address will open the OPAC. The second address will open the staff interface.

Save the file by pressing Ctrl+O, followed by Enter. Press Ctrl+X to close the editor.

Step 7: Create the DNS Records

Open the DNS management area provided by your domain registrar or hosting company.

Create two A records:

You can check whether the records are working with:

dig +short library.example.com
dig +short library-intra.example.com

Both commands should display your server’s public IP address.

DNS changes do not always become active immediately. In some cases, you may need to wait before the new records work everywhere.

If Koha only needs to work inside your school, college, or office network, read how to make Koha available on a local network.

Step 8: Enable the Required Apache Modules

Koha uses several Apache modules. Enable them with these commands:

sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers
sudo a2enmod proxy
sudo a2enmod proxy_http

Restart Apache:

sudo systemctl restart apache2

Test the Apache configuration:

sudo apache2ctl configtest

You should see:

Syntax OK

If Apache reports an error, read the message carefully before moving to the next step.

Step 9: Create a Koha Instance

Create a Koha instance named library:

sudo koha-create --create-db library

This command creates:

• A new Koha instance
• A MariaDB database
• A database user
• A secure database password
• Koha configuration files
• Apache virtual-host settings

Check the available Koha instances:

sudo koha-list

The output should contain:

library

Enable the Apache site if it is not already enabled:

sudo a2ensite library

Reload Apache:

sudo systemctl reload apache2

Check the Apache virtual hosts:

sudo apache2ctl -S

Look for the OPAC and staff hostnames in the output.

Step 10: Enable Plack

Plack helps improve the performance of Koha’s staff interface. Without it, Koha may feel slower because the application has to do more work for each request.

Enable Plack for your instance:

sudo koha-plack --enable library

Start it:

sudo koha-plack --start library

Restart Apache:

sudo systemctl restart apache2

Check Plack’s status:

sudo koha-plack --status library

When you make an important configuration change, restart Plack:

sudo koha-plack --restart library

Step 11: Configure the Firewall

The firewall should allow SSH and normal web traffic.

Allow SSH first:

sudo ufw allow OpenSSH

Allow HTTP and HTTPS:

sudo ufw allow "Apache Full"

Enable the firewall:

sudo ufw enable

Check its status:

sudo ufw status

Do not open the MariaDB port to the public internet for a normal Koha installation.

Step 12: Complete the Koha Web Installer

Open the staff interface in your browser:

http://library-intra.example.com

Koha will display its web installer.

The installer requires the database username and password created for your instance. These details are stored in:

/etc/koha/sites/library/koha-conf.xml

View the file with:

sudo less /etc/koha/sites/library/koha-conf.xml

Find the database user and pass values. Keep these details private.

The web installer will guide you through the following stages:

1. Checking the system requirements
2. Connecting to the database
3. Creating the Koha database tables
4. Selecting MARC21 or UNIMARC
5. Loading required data
6. Opening the onboarding tool

The official Koha manual also separates installation into the server installation, web installer, and onboarding stages. Koha installation manual

Step 13: Complete Koha Onboarding

After the web installer finishes, Koha will open the onboarding tool.

You will be asked to create:

• Your first library or branch
• A patron category
• A patron account
• An item type
• A circulation rule

The first patron account normally becomes the Super Librarian account.

Use a strong username and password. Avoid simple details such as:

Username: admin
Password: AdminPass123

Simple passwords are easy to guess and should never be used on a live server.

After onboarding, sign in to the staff interface and confirm that you can open the Administration, Cataloguing, Patrons, Circulation, and Reports modules.

Step 14: Enable HTTPS

HTTPS protects login details and other information exchanged between the browser and the Koha server.

Install Certbot:

sudo apt install -y certbot python3-certbot-apache

Request a certificate for both Koha addresses:

sudo certbot --apache \
  -d library.example.com \
  -d library-intra.example.com

Enter your email address and follow the instructions. Select the option to redirect HTTP traffic to HTTPS if it is offered.

Test automatic renewal:

sudo certbot renew --dry-run

After HTTPS is active, use:

• OPAC: https://library.example.com
• Staff interface: https://library-intra.example.com

The staff interface contains private library and patron information. Restricting it to an institutional network or VPN can provide additional protection.

Step 15: Create and Check Koha Backups

Koha includes its own backup commands. These are better than placing a visible database password inside a custom mysqldump command.

Create a backup:

sudo koha-dump library

Check the default backup folder:

sudo ls -lh /var/spool/koha/library/

A Koha backup normally includes:

• A compressed SQL database file
• A compressed configuration archive

These files are needed when restoring the instance.

Koha packages also include an automated backup task. You can review it with:

sudo nano /etc/cron.daily/koha-common

A typical retention command looks like this:

koha-run-backups --days 14 --output /var/spool/koha

Keeping backups on the same server is not enough. A disk failure could destroy the live system and its local backups at the same time. Copy important backups to another server or secure storage location.

Our Koha backup and restoration guide explains this process in more detail.

Step 16: Check the Installation

List the Koha instances:

sudo koha-list

Check Apache:

sudo systemctl is-active apache2

Also Check MariaDB:

sudo systemctl is-active mariadb

Check Plack:

sudo koha-plack --status library

Test the Apache configuration:

sudo apache2ctl configtest

Finally, open both Koha addresses in a private browser window. Confirm that the OPAC opens at the public address and the staff login opens at the intranet address.

Configure Email After Installation

A new Koha installation is not automatically ready to send reliable email.

Email is required for:

• Overdue notices
• Advance notices
• Hold notifications
• Password recovery
• Checkout receipts
• Other messages sent to patrons

Once the main installation is working, follow the Koha email configuration tutorial to connect the system to a suitable mail service.

Do not delay testing email until the library begins sending real notices.

Common Koha Installation Problems

Unable to locate package koha-common

This usually means the Koha repository was not added correctly.

Check the repository file:

cat /etc/apt/sources.list.d/koha.list

Then run:

sudo apt update

Read the update output for repository or signing-key errors.

The Apache default page appears

This often happens when the requested domain is not matching the Koha virtual host.

Run:

sudo apache2ctl -S

Check the hostname, DNS records, and Koha Apache configuration.

The staff interface does not open

Check whether:

• The staff DNS record points to the correct server
• Apache is running
• The Koha site is enabled
• Port 80 or 443 is allowed
• The staff hostname is present in the Apache configuration

Database connection failed

Check that the instance exists:

sudo koha-list

Then review:

/etc/koha/sites/library/koha-conf.xml

Do not replace its database values with credentials from a manually created database.

Certbot cannot issue the certificate

Make sure:

• Both DNS records point to the server
• Ports 80 and 443 are open
• Apache is running
• The domain names are typed correctly
• The server can be reached from the internet

Koha feels slow

Check Plack:

sudo koha-plack --status library

You should also check the server’s memory, CPU usage, storage, database performance, and available disk space.

A command works, but the change does not appear

Restart Plack and reload Apache:

sudo koha-plack --restart library
sudo systemctl reload apache2

For more solutions, see our Koha troubleshooting guide for beginners.

Useful Koha Commands

Replace library with your own Koha instance name.

Koha Installation FAQs

Can I install Koha on Ubuntu?

Yes. Koha provides packages for modern Debian-based operating systems, including Ubuntu. Ubuntu 24.04 LTS is a suitable choice for a server installation.

Can Koha run on Windows?

Koha is mainly designed to run on Linux. A Windows user can run Ubuntu inside VirtualBox or another virtual machine, but a dedicated Ubuntu server is more suitable for a live library system.

Is Koha free to use?

Yes. Koha is free and open-source software. However, a library may still need to pay for hosting, data migration, staff training, customization, maintenance, backups, and technical support.

Which command installs Koha?

After adding the official repository, install Koha with:

sudo apt install koha-common

Do I need to create the Koha database manually?

No. This command creates the database and related configuration:

sudo koha-create --create-db library

What is the difference between manual and script installation?

Manual installation lets you run and understand each command separately. It is better for learning and troubleshooting.

The script method performs several steps automatically. It can save time, but the script should be inspected and tested before it is used on an important server. See our Koha installation script method for comparison.

Where are Koha’s configuration files stored?

Files for an instance named library are normally stored in:

/etc/koha/sites/library/

The main instance configuration file is:

/etc/koha/sites/library/koha-conf.xml

How do I open Koha after installation?

Using the example configuration in this guide:

OPAC: https://library.example.com
Staff interface: https://library-intra.example.com

Your actual addresses will depend on the instance name and domain settings.

Final Words

A manual Koha installation on Ubuntu takes more time than running an automated script, but it gives you better control over the server. You can see how the repository, database, Apache site, OPAC, staff interface, Plack, firewall, HTTPS, and backups work together.

Do not rush to place the system online immediately after completing the installer. Test the catalogue, circulation rules, patron permissions, email delivery, backups, and HTTPS first.

If you prefer a quicker setup, compare this manual process with the automated Koha installation script method. For broader background information, visit our complete beginner’s guide to Koha.