Installation & setup
MySQL or MariaDB for Koha, and which version
Install MariaDB from your distribution's own repository. Both work — Koha depends on a virtual package that either satisfies — but one of them is what everybody else is running.
Updated 2026-08-12 · Tested against Koha 26.05
Install MariaDB from your distribution's own repository — sudo apt install mariadb-server — and let the version be whatever that release ships. Koha depends on the virtual package virtual-mysql-server, so MySQL satisfies it equally; MariaDB is the recommendation because it is what the community runs, tests against and answers questions about.
Step 1Install it before you create the instance
$ sudo apt -y install mariadb-server$ sudo systemctl enable --now mariadb$ sudo mysql_secure_installationOrder matters: koha-create does not install a database server, it connects to one. Creating an instance first simply fails.
You will not need the root password again during normal use. Koha connects as its own generated user, one per instance, and koha-mysql reads those credentials out of the instance configuration for you:
$ sudo koha-mysql library -e "SELECT VERSION();" VERSION()10.11.13-MariaDB-0+deb12u1Which one, honestly
| Choice | What it means for you |
|---|---|
| <strong>MariaDB from the distribution</strong> | The default. Present in Debian and Ubuntu, satisfies Koha's dependency, and matches what almost every published Koha answer assumes. |
| <strong>MySQL from the distribution</strong> | Works. You will occasionally hit a difference in defaults — SQL mode, authentication plugin — that a MariaDB-shaped answer does not mention. |
| <strong>Either, from the vendor's own repository</strong> | Adds a second moving part with its own upgrade schedule, for a version Koha does not ask for. Worth it only if your institution already standardises on it. |
| <strong>A managed cloud database</strong> | Supported — the host and credentials are just configuration — but plan for the latency of every query crossing a network, and check that the provider allows the settings below. |
The version question is usually the wrong question
The settings that actually matter
Two, and both are about characters rather than performance.
Character set
A library catalog contains names, titles and subjects in scripts the person who installed the server does not read. The database has to store all of them, which means UTF-8 throughout — the database, the tables and the connection. A modern Debian or Ubuntu MariaDB defaults to a UTF-8 collation, so this is normally already right, and worth confirming rather than assuming:
$ sudo koha-mysql library -e "SHOW VARIABLES LIKE 'character_set_database';" Variable_name Valuecharacter_set_database utf8mb4Getting this wrong is not a cosmetic problem: records imported into a database with the wrong character set are damaged at the moment they are written, and no later fix recovers what was lost. Check it before the first import, not after.
SQL mode
Strict SQL modes cause Koha to reject writes that older, laxer settings accepted — most visibly during a migration, where a stray empty value in a date column becomes an error rather than a zero date. If an import fails with Incorrect date value or Data truncated, this is why, and the answer is to clean the data rather than to loosen the mode permanently on a live catalog.
Whatever you choose, back it up as an instance
A mysqldump of the Koha database is not a Koha backup. It leaves out koha-conf.xml — the database credentials, the ports, the paths — so restoring it onto a rebuilt server gives you a database nothing can open. koha-dump captures both, which is why it is the command to use: see backing up Koha with koha-dump.
Why Koha does not simply require one of them
The packaging depends on mysql-client | virtual-mysql-client rather than on a named product. virtual-mysql-client is a Debian convention: any package providing a MySQL-compatible client — MariaDB's, MySQL's — satisfies it. The same pattern is used for the server. So the dependency states what Koha needs (a MySQL-protocol database) instead of who supplies it.
That is why both work, and why the honest recommendation is about the community rather than about the software. When notices stop sending or an index needs rebuilding, the answer you find will have been written by somebody running MariaDB on Debian. Matching that costs nothing at install time and saves an afternoon later — which is the same reasoning behind picking the distribution.
The one thing worth deciding deliberately is where the database runs. On the same server is simplest and is what the packaging assumes. Elsewhere is entirely supported, and turns every page load into a network round trip — fine on a fast local network, painful across a WAN, and the first thing to check when a catalog is inexplicably slow.
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.
Koha packages or a source install: which one you want
Almost every library wants the packages. Here is exactly what a source install gives up — the koha-* commands, the upgrade path, and most published answers — and the two cases where it is still right.
Which Ubuntu or Debian version to install Koha on
The newest Ubuntu LTS or current Debian stable, and nothing else — here is the one command that confirms it before you build the server, and what each other choice actually costs.
apt cannot install koha-common
Unmet dependencies, NO_PUBKEY, or apt claiming the package does not exist. Four causes, in the order they actually occur, with the one command that tells you which of them you have.
Apache will not start: Invalid command 'RewriteEngine'
Apache refuses to start after enabling a Koha site because mod_rewrite is not enabled. One command fixes it — and the same class of error covers the other three modules Koha needs.

