Koha Backup and Restoration Guide for Beginners

Koha backup is not only a technical task. It is the safety plan for your library system.

Koha stores important library data, including catalogue records, item barcodes, patron records, checkouts, holds, fines, notices, reports, staff permissions, and system settings. If your Koha server fails, a good backup can save days or even weeks of manual recovery work.

This Koha backup and restore guide explains the safest beginner-friendly methods for backing up and restoring Koha on a Linux server. It covers Koha package tools such as koha-dump, koha-run-backups, and koha-restore.

It also explains manual MySQL or MariaDB backup using mysqldump.

This guide is written for beginners who manage package-based Koha installations on Debian or Ubuntu.

You will learn what to back up, how to find your Koha instance name, how to restore safely, how to rebuild the search index, and how to test Koha after recovery.

What Is the Best Way to Back Up Koha?

For most package-based Koha installations, the best beginner-friendly backup method is koha-dump.

It creates a Koha database dump and a configuration archive for the Koha instance.

For scheduled backups, use koha-run-backups.

Use mysqldump only when you need a database-only backup because it does not include Koha configuration files, uploaded files, OPAC customizations, Apache settings, or other server-level files.

A safe Koha backup plan should include three things:

1. A full Koha backup.
2. An off-server copy.
3. A tested restore process.

You may also Like: Koha Troubleshooting Guide for Beginners

Why Koha Backups Matter for Every Library

Koha stores important library data in a database. The data can include bibliographic records, item records, barcodes, patrons, checkouts, renewals, holds, fines, reports, notices, system preferences, and staff permissions.

Losing this data can stop circulation, damage patron trust, and make catalog recovery difficult.

A backup protects your library when something goes wrong.

It helps when a server crashes, a database import fails, a Koha upgrade breaks, a staff member deletes data by mistake, or a migration does not go as planned.

For a small school library, a backup may protect a few thousand records.

For a college, university, or public library, it may protect years of circulation history and cataloging work.

A good backup plan should answer three simple questions:

• What data is backed up?
• Where is the backup stored?
• Has the backup been restored successfully in a test environment?

A backup that has never been tested is only a hope.

A tested restore is a real recovery plan.

What Data Should a Complete Koha Backup Include?

A complete Koha backup should include more than the MySQL or MariaDB database.

Many beginner tutorials only show how to export the Koha database.

That is useful, but it is not a complete disaster recovery plan.

Koha can also depend on configuration files, uploaded files, OPAC customizations, search indexes, Apache settings, cron jobs, and backup logs.

Koha Data	Why It Matters	Backup Priority
Koha database	Stores bibliographic records, items, patrons, checkouts, holds, fines, reports, notices, and settings	Very high
Koha configuration files	Store instance settings, database credentials, ports, and paths	Very high
Uploaded files	Needed if your Koha uses file uploads or attached documents	High
OPAC customizations	Include custom CSS, JavaScript, logos, images, and theme settings	High
Zebra indexes	Help Koha search work quickly after restore	Medium
Cron job settings	Run notices, indexing, cleanup, fines, and other background tasks	High
Apache or web server configuration	Helps restore URLs, ports, and site access	Medium
Backup logs	Help confirm that backups completed successfully	Medium

If you only back up the database, you may still be able to recover records and patrons.

However, you may lose custom design files, uploaded documents, local configuration, web server settings, or automation settings.

That is why koha-dump is usually safer than a basic mysqldump backup for package-based Koha systems.

Read Also: Koha SQL Reports Generator

Koha Backup Methods Compared

Different backup methods serve different purposes.

Beginners often ask which method is best.

For modern package-based Koha installations, koha-dump is usually the best starting point because it is made for Koha instances.

Method	Best For	What It Backs Up	Beginner Rating
koha-dump	Full backup of one Koha instance	Database and Koha site/configuration files, with options for uploaded files and indexes	Best default option
koha-run-backups	Automated scheduled backups	Uses koha-dump and keeps backups for a selected number of days	Best for production
mysqldump	Database-only backup or manual migration	Koha database only	Useful but incomplete
MARC export	Catalog record preservation	Bibliographic, item, or authority records	Not a full backup

Use koha-dump for a full backup. Similarly, use koha-run-backups for scheduled backups.

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, or newer
Server OS	Ubuntu or Debian
Backup location	/backups/koha/
Free disk space	More than database size plus uploaded files
Root or sudo access	Required for most commands
Off-server storage	Another server, external drive, or secure cloud storage
Test restore plan	Separate test server or virtual machine

Warning: Do not restore a live Koha database without creating a fresh backup first.

Restore commands can overwrite existing records, patrons, circulation history, reports, notices, and system settings.

Important: Use the Koha instance name with Koha commands.

Use the database name with MySQL or MariaDB commands.

For example, if your instance name islibrary, your database name is usually koha_library.

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 --enabled

If the output is:

library

Then your Koha instance name is:

library

Your database name is usually:

koha_library

Use the instance name with Koha commands such as:

sudo koha-dump library
sudo koha-upgrade-schema library
sudo koha-rebuild-zebra -v -f library

Use the database name with MySQL or MariaDB commands such as:

sudo mysqldump -u root -p koha_library > koha_library.sql

Method 1: Full Koha Backup Using koha-dump

For a package-based Koha installation, the easiest full backup command is:

sudo koha-dump library

Replace library with your real Koha instance name.

This creates backup files for the Koha instance.

A typical backup includes:

• A compressed SQL database dump.
• A compressed configuration and site archive.

You may find the backup files under a Koha spool or backup directory such as:

/var/spool/koha/library/

Check the files with:

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

You may see files similar to:

library-2026-05-17.sql.gz
library-2026-05-17.tar.gz

The .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 in the backup.

Run:

sudo koha-dump --uploaded_files library

If temporary uploaded files also matter, run:

sudo koha-dump --uploaded_files --uploaded_temp_files library

This is useful when Koha stores attached files, documents, or other uploaded materials.

Exclude Zebra Indexes to Reduce Backup Size

Zebra indexes can make backup files larger.

If you want a smaller backup and you are comfortable rebuilding the search index after restore, use:

sudo koha-dump --exclude-indexes library

This keeps the backup lighter.

However, after restoring Koha, you must rebuild Zebra so OPAC and staff search work correctly.

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 7

This command stores backup files under an instance folder inside the output directory.

For example, if your instance is called library, the files may be stored under:

/backups/koha/library/

The command keeps backups for 7 days.

To check the files, run:

ls -lh /backups/koha/library/

If you want smaller backups, you can exclude Zebra indexes:

sudo koha-run-backups --output /backups/koha --days 7 --exclude-indexes

For a beginner-friendly production setup, keep at least 7 daily backups and one weekly off-server backup.

If your library has heavy circulation, keep backups for a longer period.

A better plan may include 30 daily backups, weekly backups for several months, and a monthly archive.

Method 3: Manual Koha Database Backup Using mysqldump

Manual database backup is useful when you only need the database. It is also common in older Koha migration tutorials.

However, remember that mysqldump backs up the database only.

It does not automatically back up:

• Koha configuration files.
• Uploaded files.
• OPAC design files.
• Apache settings.
• Cron jobs.
• Local scripts.
• Search indexes.

Basic database backup:

sudo mysqldump -u root -p koha_library > koha_library.sql

Compressed database backup:

sudo mysqldump -u root -p koha_library | gzip > koha_library.sql.gz

Safer backup for InnoDB tables:

sudo mysqldump -u root -p \
  --single-transaction \
  --routines \
  --triggers \
  --events \
  koha_library | gzip > koha_library_$(date +%F).sql.gz

This is helpful for a database-only backup. Still, 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.gz

Run:

sudo koha-restore library-2026-05-17.sql.gz library-2026-05-17.tar.gz

Use this method on a clean or prepared server.

The restore process may stop if files from the configuration dump already exist on the server.

This is a safety check to reduce the risk of accidental overwriting.

Warning: Do not run koha-restore casually on a live server. Test it first on a separate server or virtual machine whenever possible.

Screenshot Placeholder

Add a screenshot here showing a successful restore command output.

Use a caption such as:

Successful Koha restore using koha-restore.

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.

This method is useful, but it is not as complete as restoring a full koha-dump backup.

Step 1: Stop Services

Stop Apache:

sudo systemctl stop apache2

Stop memcached:

sudo systemctl stop memcached

If your Koha uses Plack, stop it:

sudo koha-plack --stop library

Replace library with your Koha instance name.

Step 2: Open MySQL or MariaDB

sudo mysql -u root -p

Step 3: Drop and Recreate the Database

Warning: This removes the current Koha database.

Only run this if you are sure you are restoring the correct backup.

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.sql

For a compressed SQL file:

gunzip -c koha_library.sql.gz | sudo mysql -u root -p koha_library

After importing, continue with schema upgrade, search index rebuild, service restart, and testing.

Why 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 may need to run:

sudo koha-upgrade-schema library

Think of schema upgrade like adjusting the shelves before placing the books back.

Your data may be present, but the newer Koha version needs the database structure to match its current rules.

Run this command especially when:

• You moved a database from an older Koha version to a newer version.
• You imported a manual SQL backup.
• You migrated from an old server to a new server.
• The staff interface shows database or upgrade warnings.

Use the Koha instance name, not the database name.

Correct:

sudo koha-upgrade-schema library

Incorrect:

sudo koha-upgrade-schema koha_library

Why Search Index Rebuild Is Important After Restore

After restoring Koha, your records may exist in the database but not appear correctly in OPAC or staff search.

This often happens because the search index needs to be rebuilt.

For Zebra-based Koha installations, run:

sudo koha-rebuild-zebra -v -f library

If search is broken after restore, do not panic.

First confirm the database imported correctly.

Then rebuild the search index, restart services, and test OPAC search again.

Note About Zebra, Elasticsearch, and OpenSearch

This guide mainly uses Zebra commands because Zebra is common in package-based Koha installations.

Some Koha systems may use Elasticsearch or another configured search setup.

If your Koha installation uses Elasticsearch or OpenSearch, follow the indexing steps for your configured search engine.

You can check the Koha SearchEngine system preference in the staff interface.

If you are not sure, ask your Koha administrator before running search rebuild commands.

Restart Services After Restore

After schema upgrade and search index rebuild, restart the main services.

Restart memcached:

sudo systemctl restart memcached

Restart Apache:

sudo systemctl restart apache2

If using Plack, restart it:

sudo koha-plack --restart library

If needed, restart Zebra:

sudo koha-zebra --restart library

Now 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
Email sending	Test notice or email delivery if configured
Permissions	Staff roles and permissions still work correctly

Common Koha Backup and Restore Errors

1. Wrong Instance Name

This happens when a user runs a Koha command with the database name instead of the Koha instance name.

Incorrect:

sudo koha-upgrade-schema koha_library

Correct:

sudo koha-upgrade-schema library

Use this command to confirm the instance name:

sudo koha-list --enabled

2. Search 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 library

Then restart services and test OPAC search again.

3. Backup File Is Too Large

Large Zebra indexes, logs, and uploaded files can increase backup size.

If you need a smaller backup, exclude indexes and rebuild them after restoration.

sudo koha-dump --exclude-indexes library

You can also exclude logs when suitable:

sudo koha-dump --exclude-logs library

4. Uploaded 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 library

If temporary uploaded files matter, use:

sudo koha-dump --uploaded_files --uploaded_temp_files library

5. Restore 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.

6. Database Import Fails

A database import may fail because of:

• Wrong database name.
• Wrong MySQL user.
• Corrupt SQL file.
• Not enough disk space.
• Character set mismatch.
• Missing permissions.

Check the backup file first:

ls -lh koha_library.sql.gz

Test whether the compressed file can be read:

gunzip -t koha_library.sql.gz

If this command returns no error, the gzip file is readable.

7. OPAC Design Looks Broken After Restore

If the OPAC design looks broken, check:

• Custom CSS.
• JavaScript.
• Logo files.
• Theme settings.
• Apache configuration.
• Uploaded media files.
• System preferences related to OPAC appearance.

A database-only restore may not include all custom design files.

Simple Backup Schedule for Small Libraries

A small library does not need a complex enterprise backup system. However, it does need consistency.

A backup that is never tested is not enough.

Backup Task	Recommended Frequency
Database backup	Daily
Full Koha backup with configuration	Daily or weekly
Off-server copy	Daily or weekly
Test restore	Monthly
Pre-upgrade backup	Before every Koha upgrade
Backup log review	Weekly
Security review of backup storage	Monthly

For a small library, a simple plan may look like this:

• Daily automated backup using koha-run-backups.
• Weekly off-server copy.
• Monthly test restore.
• Manual backup before every Koha upgrade.
• Backup logs checked every week.

Beginner Example: Moving Koha From an Old Server to a New Server

Imagine your old server has a Koha instance called library. You want to move it to a new server. On the old server, create a full backup:

sudo koha-dump --uploaded_files library

Check the backup files:

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

Copy the backup files to the new server:

scp /var/spool/koha/library/library-2026-05-17.* user@newserver:/backups/

On the new server, go to the backup folder:

cd /backups

Restore using:

sudo koha-restore library-2026-05-17.sql.gz library-2026-05-17.tar.gz

If you restored an older database into a newer Koha version, run:

sudo koha-upgrade-schema library

Rebuild Zebra if needed:

sudo koha-rebuild-zebra -v -f library

Restart services:

sudo systemctl restart memcached
sudo systemctl restart apache2

If using Plack:

sudo koha-plack --restart library

Finally, test:

• Staff login.
• OPAC search. and koha other optional link: Patron records, Bibliographic records, Circulation, Holds, Reports etc.

Security Tips for Koha Backup Files

Koha backups can contain sensitive library data. This may include patron names, contact details, borrowing history, staff accounts, reports, and internal settings. Therefore treat backup files like confidential library records.

Create a protected backup directory:

sudo mkdir -p /backups/koha
sudo chmod 700 /backups/koha

Restrict backup file access:

sudo chmod 600 /backups/koha/*.gz

It is recommended not to store backups in a public web directory. Similalry also do not send unencrypted backup files through email. Use encrypted off-server storage whenever possible.

Good storage options include:

• A secure backup server.
• An encrypted external drive.
• A secure cloud storage account.
• A managed backup service.
• A private network storage location.

Also keep a written restore procedure.

During a real server failure, clear instructions save time.

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 with temporary uploaded files	sudo koha-dump --uploaded_files --uploaded_temp_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
Compressed manual backup	sudo mysqldump -u root -p koha_library | gzip > koha_library.sql.gz
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
Restore compressed SQL	gunzip -c koha_library.sql.gz | sudo mysql -u root -p koha_library
Upgrade schema	sudo koha-upgrade-schema library
Rebuild Zebra	sudo koha-rebuild-zebra -v -f library
Restart services	sudo systemctl restart memcached apache2
Restart Plack	sudo koha-plack --restart library
Restart Zebra	sudo koha-zebra --restart library

Final Thoughts

A good Koha backup and restore plan is more than one command. You should understand what Koha ILS stores, which backup method fits your situation, where backup files are kept, and how to test the system after recovery.

For most modern package-based Koha servers, start with koha-dump full backups. Use koha-run-backups for automation. Perform the restore process on a test server. Document every step.

This is the safe way for library staff to turn a backup file into a real recovery plan. For official Guidelines, please visit the Koha community

FAQs About Koha Backup