A Koha backup is not just a technical task. It protects your library’s catalog, patron records, circulation history, reports, notices, item data, and system settings. If your Koha server fails, a good backup can save days or even weeks of work.
This Koha backup and restoration guide explains the safest beginner-friendly methods for backing up and restoring Koha. It covers official Koha package tools such as koha-dump, koha-run-backups, and koha-restore, plus the manual MySQL or MariaDB method using mysqldump.
The guide is written for beginners who manage Koha on a Linux server, especially Debian or Ubuntu package-based installations. You will learn what to back up, how to restore your system, how to rebuild search indexes, and how to test Koha after recovery.
Why Koha Backups Matter for Every Library
Koha stores important library data in a database. That data may include bibliographic records, item barcodes, patrons, checkouts, holds, fines, reports, notices, system preferences, and staff permissions. Losing this data can stop circulation, damage patron trust, and make catalog recovery very difficult.
A backup is your recovery plan. It protects the library when a server crashes, a database import fails, an upgrade breaks, a staff member deletes data by mistake, or a migration goes wrong. For a small school library, this may mean saving a few thousand records. For a college or public library, it may mean protecting years of circulation history.
A good backup plan should answer three simple questions: what is backed up, where it is stored, and whether it can be restored successfully.
What Data Should a Complete Koha Backup Include?
A complete Koha backup should include more than the database. Many beginner tutorials only show how to export the MySQL database, but Koha also depends on configuration files, uploaded files, search indexes, web server settings, and scheduled jobs.
| Koha Data | Why It Matters | Backup Priority |
|---|---|---|
| Koha database | Stores bibliographic records, patrons, checkouts, holds, reports, notices, and settings | Very High |
| Koha configuration files | Stores instance settings, database credentials, ports, and paths | Very High |
| Uploaded files | Needed if your Koha uses file uploads or attached documents | High |
| OPAC customizations | Includes custom CSS, JavaScript, logos, and design settings | High |
| Zebra indexes | Helps Koha search work quickly after restore | Medium |
| Cron job settings | Runs notices, indexing, cleanup, fines, and other background tasks | High |
| Apache or web server config | Helps restore URLs, ports, and site access | Medium |
| Backup logs | Helps confirm whether backups completed successfully | Medium |
Koha Backup Methods Compared
Beginners often ask which backup method is best. The answer depends on your installation type and goal. For modern Koha package installations, koha-dump is usually the best starting point because it is built for Koha.
| Method | Best For | What It Backs Up | Beginner Rating |
|---|---|---|---|
koha-dump | Full backup of one Koha instance | Database, configs, and optional uploaded files/indexes | Best default option |
koha-run-backups | Automated scheduled backups | Koha instance backups with retention settings | Best for production |
mysqldump | Database-only backup or manual migration | Koha database only | Useful but incomplete |
| MARC export | Exporting catalog records only | Bibliographic, item, or authority records | Not a full backup |
Before You Start: Beginner Safety Checklist
Before running backup or restore commands, collect the basic details of your Koha system. This avoids common mistakes and makes recovery safer.
| Item | Example |
|---|---|
| Koha instance name | library |
| Koha database name | koha_library |
| Koha version | 24.11, 25.05, 25.11 |
| Server OS | Ubuntu or Debian |
| Backup location | /backups/koha/ |
| Free disk space | More than the database and upload size |
| Root or sudo access | Required for most commands |
| Off-server storage | Another server, external drive, or secure cloud |
| Test restore plan | A separate test server or virtual machine |
Do not restore a live Koha database without a fresh backup. Restoration can overwrite existing data, so always work carefully.
How to Find Your Koha Instance Name
The Koha instance name is not always the same as the database name. This is one of the most common beginner mistakes.
Run this command:
sudo koha-list --enabledIf the output is:
libraryThen your Koha instance name is:
libraryYour database name is usually:
koha_libraryUse the instance name with Koha commands such as koha-dump, koha-upgrade-schema, and koha-rebuild-zebra. Use the database name with MySQL or MariaDB commands.
Method 1: Full Koha Backup Using koha-dump
For a package-based Koha installation, the easiest full backup command is:
sudo koha-dump libraryThis creates a backup of the Koha instance. A typical backup includes a compressed SQL database dump and a compressed configuration dump.
You may find the backup files under a Koha spool or backup directory such as:
/var/spool/koha/library/Check the files:
ls -lh /var/spool/koha/library/You may see files similar to:
library-2026-05-17.sql.gz
library-2026-05-17.tar.gzThe .sql.gz file contains the database dump. The .tar.gz file contains Koha configuration and site-related files.
Include Uploaded Files in the Backup
If your library uses Koha uploaded files, include them:
sudo koha-dump --uploaded_files libraryIf temporary uploaded files also matter, use:
sudo koha-dump --uploaded_files --uploaded_temp_files libraryExclude Zebra Indexes to Reduce Backup Size
Zebra indexes can make backups larger. If you want a smaller backup and you are ready to rebuild the index after restore, use:
sudo koha-dump --exclude-indexes libraryThis keeps the backup lighter, but you must rebuild Zebra after restoring Koha.
Method 2: Automated Koha Backups Using koha-run-backups
A one-time backup is not enough for a live library. You need regular backups. Koha includes koha-run-backups, which can create scheduled backups and keep them for a selected number of days.
Example command:
sudo koha-run-backups --output /backups/koha --days 7This stores backups in:
/backups/kohaAnd keeps backups for 7 days.
If you want smaller backups, you can exclude indexes:
sudo koha-run-backups --output /backups/koha --days 7 --exclude-indexesFor a beginner-friendly production setup, keep at least 7 daily backups and one weekly off-server backup. If your library has heavy circulation, consider longer retention.
Method 3: Manual Koha Database Backup Using mysqldump
Manual database backup is useful when you only need the database or when you are following an older migration tutorial. However, remember that mysqldump backs up the database only. It does not automatically back up Koha configuration files, uploaded files, Apache settings, or custom server files.
Basic backup:
sudo mysqldump -u root -p koha_library > koha_library.sqlCompressed backup:
sudo mysqldump -u root -p koha_library | gzip > koha_library.sql.gzSafer backup for InnoDB tables:
sudo mysqldump -u root -p \
--single-transaction \
--routines \
--triggers \
--events \
koha_library | gzip > koha_library_$(date +%F).sql.gzThis is helpful for database-only backup, but it should not replace a full Koha backup plan.
How to Restore Koha Using koha-restore
Use koha-restore when your backup was created with koha-dump.
The restore command needs two files:
library-2026-05-17.sql.gz
library-2026-05-17.tar.gzRun:
sudo koha-restore library-2026-05-17.sql.gz library-2026-05-17.tar.gzUse this method on a clean or prepared server. The restore process may stop if existing files conflict with the backup files. This protects the current server from accidental overwriting.
How to Restore a Manual SQL Backup to a New Koha Server
Use this method when you only have a .sql or .sql.gz database backup.
Step 1: Stop Services
sudo systemctl stop apache2
sudo systemctl stop memcachedIf your Koha uses Plack, run:
sudo koha-plack --stop libraryStep 2: Open MySQL or MariaDB
sudo mysql -u root -pStep 3: Drop and Recreate the Database
Be careful. This removes the current database.
DROP DATABASE koha_library;
CREATE DATABASE koha_library CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
EXIT;Step 4: Import the Backup
For an uncompressed SQL file:
sudo mysql -u root -p koha_library < koha_library.sqlFor a compressed file:
gunzip -c koha_library.sql.gz | sudo mysql -u root -p koha_libraryWhy Schema Upgrade Is Important After Restore
When you restore an older Koha database into a newer Koha installation, the database structure may not match the new Koha code. That is why you must run:
sudo koha-upgrade-schema libraryThis command upgrades the Koha database schema for the instance. Think of schema upgrade like adjusting the shelves before placing the books back. Your data may be there, but the newer Koha version needs the database structure to match its current rules.
Why Zebra Rebuild Is Important After Restore
After restoring Koha, your records may exist in the database but not appear correctly in search. This usually happens because the Zebra search index needs to be rebuilt.
Run:
sudo koha-rebuild-zebra -v -f libraryIf your search is broken after restore, do not panic. First confirm the database imported correctly, then rebuild Zebra, restart services, and test OPAC search again.
Restart Services After Restore
After schema upgrade and Zebra rebuild, restart the main services:
sudo systemctl restart memcached
sudo systemctl restart apache2If using Plack:
sudo koha-plack --restart libraryIf needed, restart Zebra:
sudo koha-zebra --restart libraryNow open the staff interface and OPAC in your browser.
Post-Restore Testing Checklist
Do not stop after the command line says the restore is complete. Test the system like a staff member and a patron.
| Area to Test | What to Check |
|---|---|
| Staff login | Staff account opens correctly |
| OPAC | Public catalog loads without errors |
| Search | Title, author, subject, barcode, and advanced search work |
| Bibliographic records | MARC records, items, call numbers, and barcodes appear |
| Patron records | Patron names, categories, permissions, and contact details appear |
| Circulation | Checkouts, check-ins, renewals, and holds work |
| Reports | Saved SQL reports are still available |
| Notices | Email templates and notices are present |
| System preferences | OPAC, circulation, cataloging, and staff settings are retained |
| Uploaded files | Attached files or uploaded documents open correctly |
| Cron jobs | Indexing, overdue notices, cleanup, and fines jobs are active |
| OPAC design | Logo, CSS, JavaScript, and theme settings look correct |
Common Koha Backup and Restore Errors
Wrong Instance Name
This happens when a user runs the schema upgrade command with the database name instead of the Koha instance name.
Incorrect:
sudo koha-upgrade-schema koha_libraryCorrect:
sudo koha-upgrade-schema librarySearch Does Not Work After Restore
The database may be restored correctly, but Zebra indexes may be missing or outdated. Run:
sudo koha-rebuild-zebra -v -f libraryBackup File Is Too Large
Large Zebra indexes, logs, and old session data can increase backup size. If you need a smaller backup, exclude indexes and rebuild them after restoration.
sudo koha-dump --exclude-indexes libraryUploaded Files Are Missing
If you used only mysqldump, uploaded files were not included. Use a Koha backup command with uploaded files included:
sudo koha-dump --uploaded_files libraryRestore Fails Because Files Already Exist
koha-restore may stop if files from the configuration dump already exist on the server. This helps avoid accidental overwriting. Use a clean server or remove conflicting files only after confirming they are safe to replace.
Simple Backup Schedule for Small Libraries
A small library does not need a complex enterprise backup system, but it does need consistency. A backup that never gets tested is only a hope. A tested restore is a real recovery plan.
| Backup Task | Recommended Frequency |
|---|---|
| Database backup | Daily |
| Full Koha backup with config | Daily or weekly |
| Off-server copy | Daily or weekly |
| Test restore | Monthly |
| Pre-upgrade backup | Before every Koha upgrade |
| Backup log review | Weekly |
Beginner Example: Moving Koha From an Old Server to a New Server
Imagine your old server has a Koha instance called library, and you want to move it to a new server.
On the old server, create a full backup:
sudo koha-dump --uploaded_files libraryCopy the backup files to the new server:
scp /var/spool/koha/library/library-2026-05-17.* user@newserver:/backups/On the new server, restore using:
cd /backups
sudo koha-restore library-2026-05-17.sql.gz library-2026-05-17.tar.gzThen run:
sudo koha-upgrade-schema library
sudo koha-rebuild-zebra -v -f library
sudo systemctl restart memcached
sudo systemctl restart apache2Finally, test the staff interface, OPAC, search, patrons, circulation, reports, notices, and uploaded files.
Security Tips for Koha Backup Files
Koha backups can contain sensitive patron information, contact details, borrowing history, staff accounts, and internal reports. Treat backup files like confidential library records.
Store backups in a protected directory:
sudo chmod 700 /backups/kohaRestrict backup file access:
sudo chmod 600 /backups/koha/*.gzUse encrypted off-server storage when possible. Do not leave Koha backups in a public web directory. Do not send unencrypted backup files through email or public file-sharing links.
Quick Command Summary
| Task | Command |
|---|---|
| List Koha instances | sudo koha-list --enabled |
| Full Koha backup | sudo koha-dump library |
| Backup with uploaded files | sudo koha-dump --uploaded_files library |
| Backup without Zebra indexes | sudo koha-dump --exclude-indexes library |
| Automated backup | sudo koha-run-backups --output /backups/koha --days 7 |
| Manual database backup | sudo mysqldump -u root -p koha_library > koha_library.sql |
| Restore Koha dump | sudo koha-restore file.sql.gz file.tar.gz |
| Restore manual SQL | sudo mysql -u root -p koha_library < koha_library.sql |
| Upgrade schema | sudo koha-upgrade-schema library |
| Rebuild Zebra | sudo koha-rebuild-zebra -v -f library |
| Restart services | sudo systemctl restart memcached apache2 |
FAQs About Koha Backup and Restoration
What is the best way to back up Koha?
For package-based Koha installations, the best beginner-friendly method is usually koha-dump because it is designed for Koha instances and can include configuration files, uploaded files, and optional Zebra indexes. Use koha-run-backups when you want automated backups with retention settings.
Is mysqldump enough for Koha?
mysqldump is enough for a database-only backup, but it is not enough for a complete Koha backup. It does not automatically include Koha configuration files, uploaded files, OPAC customizations, or server settings.
What is the difference between koha-dump and mysqldump?
koha-dump is a Koha-specific backup tool. It can back up the Koha site contents and configuration. mysqldump is a MySQL or MariaDB database backup tool. It only backs up the database you select.
Do I need to rebuild Zebra after restoring Koha?
Yes, in most manual restore or migration cases, you should rebuild Zebra. If you skip this step, records may exist in the database but fail to appear in OPAC or staff search.
What is koha-upgrade-schema?
koha-upgrade-schema updates the database structure so it matches the installed Koha version. It is especially important when restoring an older Koha database into a newer Koha installation.
Where are Koha backups stored?
The exact location depends on your command and configuration. Many Koha package backups are placed under /var/spool/koha/, while koha-run-backups --output /backups/koha stores them in the output directory you choose.
Can I restore an old Koha database to a newer version?
Yes, but you must be careful. After importing the old database, run koha-upgrade-schema, rebuild Zebra, restart services, and test all important library workflows. Very old Koha versions may need a staged migration or MARC/CSV export approach.
Should I include Zebra indexes in my backup?
Include Zebra indexes if you want faster recovery and have enough storage. Exclude them if you want smaller backups and are comfortable rebuilding the index after restore.
How often should a library back up Koha?
A live library should usually back up Koha daily. Small libraries can keep 7 to 30 days of backups. Larger libraries should use longer retention, off-server storage, and regular restore testing.
Can I export MARC records instead of a full Koha backup?
MARC export is useful for catalog preservation, sharing records, or emergency bibliographic recovery. However, it is not a full Koha backup because it does not include patrons, circulation history, system preferences, reports, or staff settings.
Final Thoughts
A good Koha backup and restoration guide should teach more than one command. Beginners need to understand what Koha stores, which backup method fits their situation, how to restore safely, and how to test the system after recovery.
For most modern Koha servers, start with koha-dump for full backups, use koha-run-backups for automation, keep off-server copies, and test your restore process regularly. Use mysqldump when you need a database-only backup, but do not treat it as a full Koha disaster recovery plan.
