How to migrate to Koha from another library system

What a Koha data migration actually moves

A complete migration moves five different data sets, each with its own format and its own level of difficulty. Confusing them is the first planning mistake: many projects are quoted as "catalog migration" with only bibliographic records in mind, and then discover that the items are missing.

• Bibliographic records: the description of each work. This is what travels in MARC21 or MARCXML.
• Items: each physical copy with its barcode, call number, branch, collection and status. In Koha they live in local field 952.
• Authorities: standardized authors, subjects and corporate bodies, migrated as separate authority records.
• Patrons: the list of borrowers, with category, branch, expiry date and contact details.
• Circulation: current loans, holds, fines and history. This is the set most often left partly behind.

On top of that comes configuration, which is not migrated but rebuilt: item types, patron categories, circulation rules, holiday calendars, branches and authorized values. In a system with three branches, that reconstruction can take as long as the data load. The configuration phase is covered in our Koha implementation guide.

Step 1: inventory the source system

Before exporting anything, document your starting point. A useful inventory answers seven questions and takes one or two sessions with library staff and IT:

1. The name and exact version of the current system, and whether the original vendor still supports it.
2. How many bibliographic records, items and active patrons there are. They are not the same number: 16,620 bibliographic records can mean more than 22,000 items.
3. Which description format it uses: MARC21, UNIMARC, a proprietary format or loose fields in a database.
4. Whether there is direct access to the database (MySQL, SQL Server, ISIS) or only to an export interface.
5. Which character set it uses: UTF-8, MARC-8 or ISO 8859-1. This is the number one cause of broken accented characters after the load.
6. What happens to active loans and outstanding fines on cutover day.
7. Whether there are attachments: cover images, full-text PDFs, links to electronic resources.

Export formats by source system

The difficulty of a migration is decided in this table. Systems that export clean ISO 2709 migrate quickly; those that only give access to the data through the database require extraction work that can double the schedule.

Koha accepts two input formats for bibliographic and authority records: binary MARC (ISO 2709, .mrc files) and MARCXML. Anything else, whether CSV, XLSX, JSON or an SQL dump, must be converted first. Patrons are the exception: they are loaded with a CSV file through the patron import tool.

Mapping fields to MARC21

The mapping is the equivalence table between each field of the old system and its MARC21 tag in Koha. It is built once, documented and applied to the whole batch. Four decisions must always be explicit:

• 942$c: the item type at bibliographic level. It determines how the record behaves in circulation and in the OPAC facets.
• 952: the local item field. At minimum it needs the home library, the holding library and the item type; in practice barcode, call number, collection and acquisition date are loaded too.
• Control fields: 001, 003 and the internal identifier. If the old system had its own control number, keep it in a local field so you can audit later.
• Character encoding: decided at the start and verified in the first test batch. Fixing accents in 20,000 records already loaded costs more than redoing the conversion.

A frequent mistake in spreadsheet migrations is loading the whole title into 245$a without separating the subtitle (245$b) or the statement of responsibility (245$c). The catalog loads and looks fine on screen, and then author searches and sorting fail. Fix it in the conversion, not afterward.

Cleaning duplicates and controlling authorities

Almost no legacy catalog arrives clean. In the cleanup projects BiblioLabTech has run on collections of around 9,000 records, typically between 3% and 10% of the records had some problem: exact duplicates, duplicates through title variants, authors written three different ways, uncontrolled subjects, mistyped ISBNs or records with no item attached.

Cleanup happens before the final load, on the converted file, because that is when bulk rules can be applied. Koha also offers matching rules during import: it can compare by ISBN (020$a), by ISSN (022$a) or by Koha's internal identifier, and decide whether to ignore, replace or add the incoming record. Defining that rule is mandatory when loading in several batches or merging branches that share titles.

Authorities deserve an explicit decision: migrate them, rebuild them from the bibliographic records, or leave them for a second phase. Migrating bibliographic records without authorities works, but it leaves access-point control pending.

Items, patrons and circulation

Items are loaded embedded in field 952 of each record, which avoids a second pass. If the source system delivers items in a separate table, they must be joined to the bibliographic record during conversion using the shared identifier. This is the part that brings the most surprises when there are several branches: one title with copies on three campuses must end up as one bibliographic record with three or more 952 fields, not as three duplicate records.

Patrons are loaded by CSV, with card number and surname as mandatory fields, plus any field the institution has marked as mandatory in its configuration. Two practical warnings: empty columns overwrite existing data with blanks, and passwords are sent in plain text for Koha to hash, so the file must be treated as sensitive data and deleted when the load is done.

On circulation, the honest decision is usually this: migrate current loans and active holds, and do not migrate the full history. The history rarely justifies its conversion cost, and if it is needed for statistics it can be kept as a separate archive or loaded later, once in production.

Test loads, validation and cutover

No serious migration loads straight into production. The proven sequence is:

1. Pilot batch of 200 to 1,000 representative records: books, serials, theses, audiovisual material and at least one difficult case from each branch.
2. Pilot review by library staff in the real catalog, not in a spreadsheet: search by author and subject, open the full record, check out an item.
3. Mapping adjustment based on what turns up. This is where encoding, misassigned subfields and item types get fixed.
4. Full load in the test environment, with all records, items and patrons.
5. Validation by counts: bibliographic records, items per branch, patrons per category and unique barcodes must match the source.
6. Freeze of the old system: a fixed date and time after which nothing is cataloged or loaned there.
7. Delta load and cutover: what was captured between the export and the freeze is migrated, the domain is pointed to Koha and the OPAC opens.

Keep the old system accessible in read-only mode for at least a month after cutover. It costs little and settles arguments.

How long a migration to Koha takes

Time depends much more on data quality than on quantity. These ranges come from projects with an export in a standard format and library staff taking part in validation:

The variable that moves these timelines most is the number of branches, not the number of records: each campus adds its own configuration, circulation rules, patrons and validation.

What usually goes wrong when you migrate to Koha

• Broken accented characters from a wrongly declared encoding conversion. Either the pilot catches it or nobody catches it in time.
• Duplicated items: a repeated 952 that the conversion reads as several different copies. Nine records can turn into dozens of phantom items.
• Repeated or missing barcodes. Koha requires uniqueness; if the collection never had barcodes, they must be generated and printed, which is a project in itself.
• Records without items, which appear in the OPAC but cannot be loaned.
• Incomplete configuration: patron categories or loan rules that were not replicated and show up on the first day of classes.
• Not freezing the old system, and ending up with two diverging catalogs for weeks.

None of these problems is rare or serious if it is caught in the test phase. All of them are expensive if they are caught in production.

After the migration

With the catalog loaded, three decisions remain open: where the instance is hosted, with what backup policy and who upgrades it. We cover them in Koha hosting: managed cloud or your own server. To size the investment, see Koha implementation cost.

If the collection arrives with poor records or gaps in description, the migration is the best moment to enrich it. Every Koha project by BiblioLabTech includes BiblioScan AI at no extra cost: the cataloger photographs the cover, title page and table of contents, and a draft MARC21 record is generated for review. BiblioLabTech migrates to Koha from commercial and open-source systems, including Aleph, Symphony, PMB and ABCD, and works remotely with libraries in any country. Learn more on our Koha service page, or send us your source system and record counts for a scoped quote.