Resources & Guides

Koha Stage MARC Records for Import: Settings Explained

Understand Koha's Stage MARC records for import settings, including file type, encoding, matching rules, record overlays, and item handling.

May 19, 2026 5 min read

Koha Stage MARC Records for Import: Settings Explained

Koha’s staged MARC import workflow lets you upload a MARC file, prepare it in the reservoir, review matches and warnings, and then import the staged records into the catalogue.

For small imports, the default settings may be enough. For migrations and updates to an existing catalogue, the staging settings matter a lot. The wrong choice can create duplicates, overwrite records unintentionally, or skip item data.

This article explains the main staging decisions in plain language.

Before you stage the file

Before using the staging tool, confirm:

the file is MARC21 binary or MARCXML;
you have a backup of the original file;
you know whether the file includes item data;
you know whether the file should create new records or overlay existing ones;
you have tested a small sample first.

If your source data is CSV, Excel, TSV, or JSON, convert it to MARC21 or MARCXML first. MARCReady can help map structured data into MARC and export a file suitable for staging in Koha.

Step 1: Choose the file

Upload the MARC or MARCXML file you want to stage.

Use a small sample first. A test file of 25 to 100 records is often enough to reveal the most important problems before you process a full catalogue.

Step 2: Choose the record type

Koha can import bibliographic records and authority records. Make sure the selected record type matches the file.

Use bibliographic records for titles, authors, subjects, publication details, and item-related import fields.

Use authority records for controlled headings such as names, subjects, and uniform titles.

Do not mix record types unless you have a deliberate migration plan.

Step 3: Check character encoding

Character encoding tells Koha how to interpret the text in the file.

Common options include:

UTF-8;
MARC-8;
ISO-8859 variants in some older workflows.

If accented characters, non-Latin scripts, or punctuation display incorrectly after staging, encoding may be the issue.

For migration work, include sample records with accents, apostrophes, symbols, and non-English characters in your test file.

Step 4: Choose a matching rule

Matching rules help Koha decide whether an incoming record matches an existing record.

This is critical when importing into an existing catalogue.

Common matching points include:

ISBN;
ISSN;
control number;
system control number;
title and author;
local identifier.

If the incoming file is for an empty Koha catalogue, matching may matter less. If the import is updating existing records, matching is essential.

A poor matching rule can cause either:

duplicates, because Koha fails to detect existing records; or
unwanted overlays, because Koha treats different records as matches.

Step 5: Decide what happens when a match is found

For imports into an existing catalogue, decide whether to:

ignore the incoming record;
replace the existing record;
add the incoming record as a new record;
merge or overlay according to your migration plan.

This decision should not be made during the final import. Test it first.

For migrations into a new Koha system, adding records as new records is often appropriate. For cleanup projects in an existing catalogue, overlays may be more sensitive.

Step 6: Decide what happens when no match is found

If no match is found, you usually choose whether to add the record as new or ignore it.

For migration imports, adding new records is normally expected.

For update batches, you may want to ignore unmatched records if the goal is only to update existing catalogue entries.

Step 7: Review item handling

Item handling controls whether Koha imports copy-level data.

Review these questions:

Does the file contain item data?
Which MARC field contains item data?
Should item data be added?
Should existing item data be preserved?
Should incoming item data replace existing item data?
Are branches, item types, and locations valid in the destination Koha system?

If item data is wrong, the import can create bibliographic records without usable holdings.

Step 8: Review staged results

After staging, check:

number of records staged;
number of records with errors;
number of matches found;
number of items staged;
sample titles and authors;
ISBN display;
warnings or failed records.

Do not skip this review.

Recommended staging workflow

Export or prepare a small file.
Review it in MARCReady if needed.
Stage the file in Koha.
Review warnings and matches.
Import into a test environment.
Check staff and OPAC display.
Adjust mapping, repair, or matching settings.
Repeat until the results are acceptable.
Stage and import the full file only after testing.

How MARCReady helps before staging

MARCReady can help before Koha staging by:

checking common MARC problems;
applying rule-based fixes for invalid indicators, ISBNs, empty subfields, duplicate fields, encoding issues, Leader, and 008;
mapping CSV, TSV, Excel, and JSON data into MARC fields;
exporting MARC21 binary or MARCXML files for Koha import.

Use MARCReady when you want to reduce the risk of staging errors before the file reaches Koha.