To install Koha on Ubuntu 24.04 LTS or later, use the Koha Community packages, create a named library instance, connect its staff and public catalogue addresses, and complete the browser installer. Then test searching, circulation and recovery before importing live library data.
This Koha installation on Ubuntu guide is for librarians, students and IT staff working on a fresh server or learning environment. Each stage includes a check, and the troubleshooting section explains how to separate DNS, Apache, port and application problems.
Version note — November 5, 2026: Koha 26.05 is the current stable series. Koha 26.05.05 was announced on October 29, 2026. This tutorial uses the official stable repository, so the actual package version will depend on what is available when you install it.
Important: Use a fresh Ubuntu 24.04 LTS server or virtual machine. This is an installation guide, not an upgrade or migration procedure for an existing library. Commands were reviewed against accessible official documentation and package scripts; this revision has not been tested end-to-end on a fresh Ubuntu VPS.
What Is Koha?
Koha is a free, open-source integrated library management system (ILMS/ILS). Libraries use it to catalogue books, register members, issue and return materials, manage holds, and provide access to an online catalogue.
Koha has two main interfaces:
- OPAC (Online Public Access Catalogue): The public-facing catalogue where readers search for library materials and access supported account services.
- Staff interface: The working area for librarians, covering cataloguing, circulation, patrons, acquisitions, reports, and administration.
If you are new to Koha, read our Koha library management system beginner’s guide.
Requirements for Installing Koha on Ubuntu
Prepare these items before running commands. A dedicated server or virtual machine makes the Apache configuration easier to understand than a machine already hosting several applications.
- Ubuntu Server 24.04 LTS, a
sudoaccount and reliable internet access. - Console or SSH access, with a way to recover access if a firewall or web configuration is wrong.
- Enough resources for the workload. For planning, 4 GB RAM and 25 GB storage are a small test-system starting point, not an official minimum or a promise of production capacity. Allow room for indexes, logs, uploads and backups.
- For the main route: two hostnames you control, DNS access, and inbound TCP 80/443 allowed by both the host and provider firewall.
- A choice of MARC21 or UNIMARC and a permanent, short instance name. Changing cataloguing formats later is a migration task, not a routine settings toggle.
| Setting | Example used throughout |
|---|---|
| Instance name | library |
| Public OPAC | library.example.com |
| Staff interface | library-intra.example.com |
| Initial Apache ports | Both hostnames on port 80; HTTPS on 443 after certificate setup |
| Database | Local MariaDB, created for the instance by Koha |
Replace example.com with your domain. Type commands without a leading $ or # prompt. Run one block at a time and stop if a command reports an error. Keep a note of your instance name, hostnames, MARC format and installed package version.
No public domain? Use the private test option in Step 7. Do not mix its port-based settings with the main two-hostname route. For network planning, also read making Koha available on a local network.
Step 1: Check Your Ubuntu Version
Open a terminal on the Ubuntu machine or connect by SSH. Check the operating system, available resources, locale and clock:
lsb_release -ds
free -h
df -h /
locale
timedatectlConfirm Ubuntu 24.04 LTS; the displayed name may include a point-release number. Check that your locale uses UTF-8. If it does not, choose and generate a UTF-8 locale before importing records. On a minimal English-language test server, one option is:
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8Use the locale appropriate to your institution rather than changing a working configuration unnecessarily. Sign out and back in after a change, then run locale again. Keep an eye on LC_ALL overrides in your shell.
Set the server timezone deliberately. For example, a library in Pakistan can use the following; readers elsewhere should substitute their own timezone:
sudo timedatectl set-timezone Asia/KarachiAn incorrect clock can complicate TLS checks, logs and scheduled work. Confirm the displayed timezone and time synchronization before continuing.
Step 2: Update Ubuntu
Refresh package information and apply available updates. Review what APT proposes rather than accepting unexpected removals:
sudo apt update
sudo apt upgradeIf a reboot is required, restart and reconnect before installing Koha. These commands update Ubuntu; they are not instructions for upgrading an existing Koha database.
Step 3: Add the Official Koha Repository
Use the community repository over HTTPS, with a key limited to that repository. The Ubuntu APT documentation deprecates apt-key and recommends a dedicated keyring with Signed-By.
Download and inspect the signing key
sudo install -d -m 0755 /etc/apt/keyrings
wget -O /tmp/koha-archive-key.asc https://debian.koha-community.org/koha/gpg.asc
gpg --show-keys --with-fingerprint /tmp/koha-archive-key.ascContinue only if the download succeeded and GnuPG recognizes a public key. Compare its identity and fingerprint with the current trusted Koha repository instructions where available. Do not import an HTML error page as a key.
sudo gpg --batch --yes --dearmor -o /etc/apt/keyrings/koha-archive-keyring.gpg /tmp/koha-archive-key.asc
sudo chmod 0644 /etc/apt/keyrings/koha-archive-keyring.gpgConfigure the package source
echo "deb [signed-by=/etc/apt/keyrings/koha-archive-keyring.gpg] https://debian.koha-community.org/koha stable main" | sudo tee /etc/apt/sources.list.d/koha.list
sudo apt update
apt-cache policy koha-commonThe last command should show a candidate version from the Koha repository. stable is a moving release alias, not a permanent version pin. Record the candidate before installation. If your institution needs a particular maintained series, verify its repository suite in the official package index and plan upgrades separately.
On a machine with an earlier Koha source, inspect existing .list and .sources entries first. Do not leave two entries for the same repository with different signed-by values. If APT reports a signature error, fix it rather than using trusted=yes or allowing unauthenticated packages.
Step 3: Install Database Server
Install the local database and secure it:
sudo apt install mariadb-server
sudo mariadb_secure_installationsystemctl is-active apache2 mariadbBoth services should report active. Investigate an inactive service before creating an instance. On Ubuntu, local MariaDB administration normally uses sudo mariadb; do not copy a sample root password from an older tutorial or change database authentication just to match it.
Keep MariaDB accessible only where it is needed. For this single-server route, you do not need a public database port, a manually created Koha database, or a separate database account prepared in advance.
Step 4: Configure Your Domain Names
Create DNS A records for library.example.com and library-intra.example.com, both pointing to this server. Set AAAA records only if the server actually has working IPv6 connectivity.
getent ahosts library.example.com
getent ahosts library-intra.example.comCheck that both names resolve to the intended machine. Resolution alone does not prove that the web ports are reachable: check the hosting firewall and routing too. Do not point these names at the WordPress hosting account unless that is also the intended Koha server.
The public catalogue and staff application can share an IP and ports because Apache selects a virtual host using the requested hostname. Visiting the bare IP is therefore not an equivalent test.
Step 6: Install Koha
sudo apt install koha-common
dpkg-query -W koha-commonThis installs the application and package utilities; it does not mean a usable library has already been configured. Keep the version output with your installation notes. Use package-managed dependencies instead of mixing a package installation with arbitrary CPAN commands from old tutorials.
Check the supporting services supplied by your installed release:
systemctl is-active apache2 mariadb memcached rabbitmq-serverA missing or inactive dependency needs investigation. RabbitMQ supports background work; a working login page does not prove that queues are processing. Do not expose database, cache or message-broker ports to the internet. The installed package documentation and utility help take precedence over development-branch examples.
Step 7: Configure Koha Site Settings
Back up the template before editing:
sudo nano /etc/koha/koha-sites.confFor the main two-hostname route, set these values:
DOMAIN=".example.com"
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra"With instance library, these settings produce library.example.com and library-intra.example.com. Keep the leading dot in the domain suffix. In Nano, save with Ctrl+O, press Enter, then exit with Ctrl+X.
Template versus active configuration: koha-sites.conf controls newly generated instances. Editing it later does not automatically rewrite an existing Apache virtual host. After instance creation, inspect /etc/apache2/sites-available/library.conf when diagnosing an address or port problem.
Optional: a private test installation on port 8080
Choose this alternative before Step 9 if you are learning on a private machine without public DNS. Use DOMAIN=".test", retain INTRASUFFIX="-intra", and set INTRAPORT="8080". Leave the OPAC on 80. Map library.test and library-intra.test to the server in each client’s hosts file or internal DNS.
127.0.0.1 library.test library-intra.testThat hosts entry is for a browser on the same machine. On another computer, replace 127.0.0.1 with the Ubuntu server’s actual LAN address. Localhost always means the computer running the browser.
sudo nano /etc/apache2/ports.confEnsure Listen 8080 appears once in the effective Apache configuration; add it only if absent. The test addresses are http://library.test and http://library-intra.test:8080. Use dummy data on an isolated environment. The public certificate commands in Step 11 do not apply to .test names. Use trusted internal HTTPS or an encrypted tunnel for sensitive access; do not publish a plain-HTTP staff login.
For any custom staff port, such as 8001, the staff VirtualHost, Apache Listen directive, firewall rule and browser URL must agree. A port change alone cannot select the correct hostname-based virtual host.
Step 8: Enable Required Apache Modules
sudo a2enmod rewrite cgi headers proxy_http
sudo apache2ctl configtestContinue only after Syntax OK. Confirm that the ITK module is enabled:
sudo apache2ctl -M | grep -E "mpm_itk|rewrite|cgi|headers|proxy_http"If mpm_itk is absent, read the error and see the troubleshooting section before changing MPM modules. A dedicated fresh Koha server is different from a shared Apache server running other applications.
sudo systemctl restart apache2Step 9: Create a Koha Library Instance
Choose the MARC format before creating the instance. For a MARC21 library using English Zebra indexing:
sudo koha-create --create-db --marcflavor marc21 --zebralang en library
sudo koha-listThe flag is --marcflavor, not --marcflavour. This creates the instance, database credentials and Apache configuration. If your library uses UNIMARC, plan that choice and its indexing requirements rather than importing those records into a MARC21 setup.
The instance list should contain library. If creation fails, retain the error and inspect what was created; do not delete its database or repeatedly run the creation command without checking.
sudo a2ensite library
sudo apache2ctl configtest
sudo apache2ctl -SInspect the hostname-to-virtual-host mapping. On a dedicated Koha machine, you may disable the unused Apache welcome site with sudo a2dissite 000-default. Do not disable another application’s site on a shared server. Reload Apache only after a successful configuration test:
sudo systemctl reload apache2Step 10: Enable Plack for Better Performance
Enable Plack after the instance exists so Apache can use the persistent application service:
sudo koha-plack --enable library
sudo koha-plack --start library
sudo koha-plack --status library
sudo apache2ctl configtest
sudo systemctl reload apache2The --enable operation changes the instance’s web configuration, while --start launches its service. Both matter. The Apache modules checked earlier include headers and proxy_http.
If the daemon is already running, inspect its status rather than treating that message as an installation failure. If a page becomes unavailable, inspect the instance logs and Apache errors before changing more settings.
Step 11: Enable HTTPS
For the public two-hostname route, arrange firewall access before certificate validation. Check your SSH port first: enabling a firewall without allowing it can lock you out. If UFW is the firewall you use, a standard-port example is:
sudo ufw status verbose
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcpReplace the OpenSSH rule if SSH uses a different port. Review existing rules and provider firewalls before enabling UFW; do not blindly replace an institutional firewall policy. Keep staff access limited to an approved network or VPN where practical.
sudo apt install certbot python3-certbot-apache
sudo certbot --apache --redirect -d library.example.com -d library-intra.example.comSubstitute your real hostnames and review the certificate prompts. Both names must resolve correctly, Apache must serve their HTTP virtual hosts, and port 80 must be reachable for the HTTP validation method. A certificate is not a fix for broken DNS or Apache configuration.
Check https://library.example.com and https://library-intra.example.com with valid certificates before entering installer credentials. This main route uses the standard HTTPS port, not :8080.
sudo certbot renew --dry-runConfirm that automatic renewal is scheduled by your chosen Certbot installation method. Keep internal test names separate from publicly validated names. Consult the official Certbot instructions if your certificate setup differs.
Step 12: Complete the Koha Web Installer
Open the secure staff interface:
https://library-intra.example.com
Koha should display its web installation screen.
You will need the database credentials generated during instance creation.
These are stored in the protected configuration file:
sudo less /etc/koha/sites/library/koha-conf.xmlRead the database <user> and <pass> values. For this instance the username is normally koha_library, but use the actual file values. These are installer/database credentials, not your Ubuntu login, MariaDB root account or the staff account you will create next.
Keep these credentials private. Do not share the file or post screenshots containing passwords. Press q to exit the viewer.
Complete the Installation Wizard
Follow the on-screen process.
1. Choose the installation language
Select an available language and continue.
2. Check dependencies
Koha checks the components required by the installer.
3. Connect to the database
Review the database connection check. The installer reads the connection configuration from the instance; resolve any failed check before continuing.
4. Create database tables
Allow Koha to create the required database structure.
5. Select the MARC format
Use the format planned at instance creation; keep the Zebra/indexing configuration and the installer’s MARC choice consistent.
- MARC21 is commonly used by libraries internationally.
- UNIMARC may be appropriate for libraries already using that cataloguing format.
6. Install initial data
Install the required initial data. Read the optional selections: sample patrons, branches and transaction data can be useful in training but should not be added uncritically to a live library. Continue to onboarding when the installer confirms completion.
The installation process is described in the official Koha 26.05 installation manual.
Step 13: Complete Koha Onboarding
After the web installer finishes, Koha opens its onboarding tool.
This helps you create the basic settings required to begin using the library management system.
Create Your Library
Enter your library’s name and code.
For example:
| Field | Example |
|---|---|
| Library name | Central Library |
| Library code | MAIN |
Create a Patron Category
Patron categories identify groups of library users.
Examples include students, faculty members, researchers, and library staff.
Choose a suitable initial category.
Create the First Staff Account
Create a staff patron account that has the required administrative permissions.
Use a strong, unique password and keep the account details securely. After onboarding, sign in with this staff patron account, not the database credentials. Create individual staff accounts with permissions suited to their roles instead of sharing the superlibrarian account.
Create an Item Type
Item types describe materials held by the library.
Examples include books, journals, reference materials, and multimedia items.
For a basic test, create a book item type such as BK.
Configure a Circulation Rule
Circulation rules determine how library materials can be borrowed.
Set an initial loan period and checkout limit appropriate for testing.
When onboarding finishes, sign in to the Koha staff interface.
You should now be able to access the main staff dashboard.
Step 14: Create Your First Koha Backup
Backups are essential for protecting library records, patron data, and configuration settings.
Create your first backup:
sudo koha-dump libraryThe command creates a backup of the Koha instance.
Check the default backup directory:
sudo ls -lh /var/spool/koha/library/A normal Koha backup includes a compressed database dump and a separate archive containing configuration and related instance files.
The dump utility has separate options for uploaded files. Check sudo koha-dump --help; if your release supports it and your library uses uploads, include them with sudo koha-dump --uploaded_files library. Also document any external storage or custom integrations that are outside the instance archive.
For more information, see our Koha backup and restoration guide.
Step 15: Verify Your Koha Installation
Before entering real library data, verify that Koha is functioning properly.
Complete these checks:
- Open the OPAC using its HTTPS address.
- Open the staff interface and sign in.
- Create a sample bibliographic record and item.
- Create a test patron.
- Check out the test item and verify the due date against your rule, then return it. Confirm the expected availability changes.
- Search for the sample record in the staff catalogue and OPAC. If you use Urdu or other non-Latin text, test its display and search with a suitable sample record.
- Confirm that backup files exist and that a restoration has been tested on an isolated machine.
You can also check Apache’s configuration:
sudo apache2ctl configtestA valid configuration normally returns:
Syntax OKIf these checks succeed, you have a working starting point for your Koha library system.
A successful basic installation does not, by itself, make the server production-ready.
Common Koha Installation Errors and Solutions
Even when you follow the correct steps, installation errors can occur. The most common problems involve Apache modules, repository settings, domain names, and service configuration.
Apache welcome page, wrong interface, or custom port problem
Start by separating “Apache can answer” from “Apache selected Koha”. An Ubuntu welcome page means the request reached a web server; it does not prove the Koha virtual host matched.
sudo apache2ctl -S
sudo apache2ctl configtest
sudo grep -nE 'VirtualHost|ServerName|ServerAlias' /etc/apache2/sites-available/library.conf
sudo grep -RnsE '^[[:space:]]*Listen[[:space:]]' /etc/apache2/ports.conf /etc/apache2/conf-enabled/
sudo ss -ltnpCompare the browser hostname and port with the virtual-host map and listening sockets. In the main route, test the two names separately. Before TLS is enabled, you can isolate Apache routing on the server with:
curl -I -H 'Host: library.example.com' http://127.0.0.1/
curl -I -H 'Host: library-intra.example.com' http://127.0.0.1/These requests check headers and routing, not a completed application login. For the optional test route, use its .test Host header and staff port 8080. For port 8001, for example, confirm <VirtualHost *:8001>, one effective Listen 8001, and the matching URL. Change only the staff virtual host when that is the intended change.
Editing koha-sites.conf after creation will not repair an already generated library.conf. Back up and correct the active file, run the configuration test, then reload. Do not remove the Apache default site as a universal fix: another site can legitimately be the default.
1. Koha Reports That mpm_itk Is Missing
The Koha instance-creation script checks whether Apache’s mpm_itk module is enabled.
If the module is installed but disabled, try:
sudo a2enmod mpm_itk
sudo apache2ctl configtest
sudo systemctl restart apache2If Apache reports a conflict between MPM modules, follow the specific instructions shown by the error. Koha’s package setup generally expects the prefork MPM with mpm_itk.
Avoid changing MPM settings blindly on a server hosting other applications.
2. Koha Reports That Rewrite or CGI Is Missing
This usually means a required Apache module is not enabled.
Repeat Step 8 and restart Apache.
Before rerunning koha-create, check whether the instance was already created so you do not attempt to create a duplicate.
3. APT Shows a GPG or Repository Error
This can happen when the Koha repository signing key is missing, unreadable, or incorrectly configured.
Review the commands in Step 5.
Make sure the repository address and signed-by path are correct.
Do not disable package-signature verification to bypass the error.
4. OPAC Works but the Staff Interface Does Not
This can happen when the staff hostname or virtual-host configuration is incorrect.
Verify that both DNS records point to the correct server.
Check that INTRASUFFIX="-intra" and INTRAPORT="80" were saved before instance creation.
Remember that the staff interface and OPAC use different hostnames.
5. Certbot Cannot Issue an HTTPS Certificate
Common reasons include:
- Incorrect DNS records
- Port 80 blocked by the server or hosting firewall
- Incorrect Apache virtual-host configuration
- Using example hostnames rather than a domain you control
Correct the underlying issue before requesting the certificate again.
6. Koha Displays an Internal Server Error
An internal server error may indicate a problem with Apache, database access, missing dependencies, or application configuration.
Check the Apache configuration and examine the Koha instance logs under:
/var/log/koha/library/Read the relevant instance error log and sudo journalctl -u apache2 -n 50 --no-pager. Check database and Plack status. The first specific error is more useful than reinstalling blindly. Redact passwords and patron data before sharing log extracts.
7. New Catalogue Records Do Not Appear in Search
If a bibliographic record saves correctly but does not appear in the catalogue search, investigate the indexing service.
Koha can use different search-engine configurations. Check the indexing services and scheduled jobs appropriate to your installed version.
Do not delete or rebuild indexes without checking the current search configuration.
Check Background Jobs, Email and Copy Cataloguing
A staff dashboard can open while important library work remains stalled. Use these checks before handing the system to library staff.
Inspect the schedule installed by your packages
dpkg -L koha-common | grep -E '/cron|systemd|timer'
systemctl list-timers --all | grep -i kohaInspect the cron files or service/timer units that actually exist for your package version. No matching timer does not, by itself, prove a fault on a cron-based installation. Check the scheduler, Koha background job screen and relevant logs. Do not paste a second copy of a job into crontab when the package already schedules it.
For stuck imports or background tasks, check the message broker and worker configuration for that release. For records missing from search, check the selected indexer; this article uses the default Zebra route, not an Elasticsearch installation.
Send and receive one real test notice
Configure the SMTP service in Administration → SMTP servers, the sending address and the applicable library settings. Use a test patron and a mailbox you control. Confirm arrival, sender details and the spam folder, rather than relying only on a “sent” status. Follow your mail provider’s SPF, DKIM and DMARC instructions for the sending domain.
For the full workflow, see the Koha email configuration tutorial. Do not publish SMTP passwords in screenshots.
Try a Z39.50 or SRU search
If your library uses copy cataloguing, configure an approved target under the Z39.50/SRU server settings. Check its current host, port, database and access requirements with the provider, then search for a known title or ISBN. Review the imported MARC record before saving. Remote targets are optional sources; their availability is not a test of whether local Koha installation succeeded.
Important Configuration After Installing Koha
Installing Koha provides the main software, but a new library system needs additional configuration before daily use.
Review the following areas:
- Library branches and locations
- Patron categories and permissions
- Item types and MARC frameworks
- Circulation and fine rules
- OPAC preferences
- Email notifications and notices
- Background jobs and indexing
- Backups and restoration
- Staff access and security
These settings depend on your library’s policies and workflows.
For detailed instructions, follow our Koha initial configuration after installation guide.
For patron notices and outgoing email, see the Koha email configuration tutorial.
Before Using Koha in Production
A live library server should have operating-system and Koha security updates, valid TLS certificates, restricted administrative access, monitoring, tested backups, correctly configured background jobs, and documented recovery procedures.
Also test real library workflows with sample data before importing the full catalogue or beginning circulation.
Frequently Asked Questions
Yes. Koha provides package-based installation options for suitable Debian and Ubuntu systems. This tutorial uses Ubuntu Server 24.04 LTS with the official Koha package repository. Always review current compatibility requirements for the release you plan to deploy.
This tutorial uses the stable repository rather than fixing a specific maintenance version.
As of November 5, 2026, Koha 26.05 is the stable series, and Koha 26.05.05 is its latest announced maintenance release. The package actually installed depends on repository availability.
Yes. Koha is free and open-source software. There is no Koha licence fee for installing and using the software.
However, server hosting, technical support, maintenance, backups, and administration may involve costs.
No. The command sudo koha-create --create-db library creates the database and database account for the instance.
Manual database creation is unnecessary for the installation method explained here.
The OPAC allows library users to search for materials and access public catalogue services.
The staff interface allows authorized librarians to manage library operations, including cataloguing, circulation, patrons, and administration.
Yes. Koha can be installed in a private test environment or on an internal network.
However, you will need an appropriate network and secure-access configuration. The public Let’s Encrypt method in this tutorial requires valid, reachable domain names.
Not automatically.
Before using Koha with real library data, configure library policies, staff access, notices, scheduled jobs, backups, security, and monitoring.
You should also test circulation, catalogue searching, and restoration procedures.
Conclusion
Before handing over Koha, demonstrate the whole path with test data: sign in as staff, find a record, issue and return its item, receive a notice, and restore a backup separately. Record the version, access details and maintenance responsibilities. For the next stage, follow our Koha initial configuration guide.
Official References
- Koha on Debian and Ubuntu — official community wiki (canonical package guide; automated retrieval was unavailable during this review).
- Koha 26.05 manual: installer and onboarding.
- Koha package source: instance creation and Plack management. Development-branch scripts may differ from installed releases; check local utility help.
- Koha backup utility source.
- Koha manual: SMTP servers.
- Official Koha APT repository and 26.05.05 release announcement.
- Ubuntu 24.04 APT key guidance, Ubuntu firewall documentation and Certbot documentation.
Editorial review: November 5, 2026. This revision expands the existing VWS Online tutorial using accessible official documentation and package-source checks. The full installation has not been run on a fresh Ubuntu 24.04 server for this revision. Confirm release compatibility and local service configuration before production deployment.




[…] Read Also: Install Koha on Ubuntu 24.04: Step-by-Step Guide (2026) […]
[…] Koha has not been installed yet, follow our manual Koha installation on Ubuntu guide. You can also compare it with the automated Koha installation script […]