Koha Barcode Range Generator

The Koha Barcode Generator creates sequential item barcode ranges that can be reviewed, exported and printed before they are added to a live Koha catalogue. It is designed for libraries that need predictable identifiers such as BK000001, BK000002 and BK000003, but it also adds the validation that a simple sequence generator often misses. Before any label is rendered, the tool checks the selected barcode symbology, the numeric range, the final value length and any existing or reserved barcodes you provide.

In a standard MARC21 Koha framework, the item barcode is stored in 952$p. Koha maps that subfield to items.barcode. The current Koha database schema documents that field as a 20-character value, so this generator treats 20 characters as a hard compatibility limit instead of allowing a visually attractive label that is too long for the target field. You can verify the mapping and field size in the official Koha schema documentation.

What the Koha Barcode Generator does

The tool builds a sequence from a prefix, starting number, numeric width and optional suffix. For example, a prefix of BK, a starting number of 1 and a numeric width of 6 produces BK000001. A quantity of 500 continues the sequence through BK000500. The generator can create as many as 1,000 labels in one browser session, subject to the numeric range and format rules you select.

Generation is only the first step. The tool also checks whether the requested suffix width can contain the complete range. If you request six numeric digits but the sequence would pass 999999, the generator stops and explains the overflow instead of quietly switching to seven digits. It also calculates the final length of every value and prevents output that exceeds Koha's 20-character item-barcode field.

You can optionally paste existing or reserved barcodes. The generator compares those values case-insensitively and can either skip conflicts while continuing the sequence or retain the conflicting values and flag them for review. This is useful when part of a range has already been assigned, labels have been pre-printed, or a migration project reserves identifiers for a specific branch or collection.

Koha 952$p and the item barcode

Koha stores item-level data separately from the bibliographic description. In a default MARC21 setup, many item attributes are represented in field 952. Home library is commonly stored in 952$a, holding library in 952$b, call number in 952$o, barcode in 952$p and item type in 952$y. The barcode is the identifier staff normally scan during circulation and inventory workflows.

The official Koha manual describes the barcode value builder as the plugin linked to 952$p in default MARC21 bibliographic frameworks. It can work with the autoBarcode system preference when libraries want Koha to generate identifiers internally. See the Koha cataloging value-builder documentation for the current behaviour.

This VWS Online generator is useful when you need to plan a range before cataloguing, prepare identifiers for a migration spreadsheet, print labels in advance, or use a numbering convention that is easier to manage outside the item editor. It does not connect to your Koha database, so it cannot know which identifiers already exist unless you provide them. That is why the reserved-barcode input is an important safety feature for production use.

How to generate a sequential Koha barcode range

1. Choose a prefix. A short code such as BK, REF or a branch abbreviation can make ranges easier to recognize. Keep the total 20-character Koha limit in mind.
2. Enter the starting number. Use the first unused numeric value in the range you have planned.
3. Choose the quantity. The tool supports 1 to 1,000 generated barcodes per run.
4. Set the numeric width. Six digits turns 1 into 000001; eight digits turns it into 00000001.
5. Add an optional suffix. Use a suffix only if it is part of the identifier that will actually be stored in Koha.
6. Select the barcode symbology. Code 128 is the recommended general-purpose option for typical alphanumeric Koha values.
7. Paste reserved barcodes if needed. Choose whether conflicts should be skipped or retained with a warning.
8. Generate and review the summary. Confirm the first value, last value, quantity, length, format and collision count before printing.
9. Print a small test batch. Scan a label and confirm the scanner returns exactly the same string that you plan to store in 952$p.

Code 128 vs Code 39 for Koha labels

Code 128 is the default choice in this tool because it can represent a broad set of printable ASCII characters efficiently. It works well for common library patterns that combine letters, digits and separators. A value such as MAIN-BK-000123 is a natural Code 128 candidate as long as the final Koha identifier remains within 20 characters.

Code 39 is also widely supported by scanners, but its character set is more restrictive. The generator accepts uppercase letters, digits, spaces and the standard Code 39 punctuation characters. Lowercase letters are not silently converted, because silently changing a barcode would make the printed value different from the identifier you intended to store. If your proposed Code 39 value contains unsupported characters, the tool asks you to correct it before labels are created.

Whichever format you choose, the important operational rule is simple: the scanner output and the value stored in Koha must match. A visually readable number under the bars is not enough if the encoded data differs.

EAN-13, UPC-A and ITF-14 check digits

EAN-13, UPC-A and ITF-14 are numeric formats with specific lengths and check-digit rules. They should not be treated like Code 128 with an arbitrary alphabetic prefix. For this reason, the generator validates the numeric payload before rendering and calculates the final check digit itself.

For EAN-13, your prefix + padded sequence + suffix must form exactly 12 numeric payload digits. The generator appends the thirteenth check digit and exports the complete 13-digit value. For UPC-A, the input pattern must form an 11-digit numeric payload and the tool appends the twelfth digit. For ITF-14, the payload must contain 13 digits before the fourteenth check digit is added.

This detail matters in a Koha workflow. If software rendered an EAN image from a 12-digit payload but exported only those 12 digits to your item spreadsheet, the scanner could return 13 digits while Koha contained 12. The VWS Online tool avoids that mismatch by exporting the same completed value that is encoded in the barcode image.

Prevent duplicate Koha barcodes

Barcode collisions can interrupt circulation and create confusing item records, so a range generator should not assume that every mathematically available number is really unused. Paste known existing identifiers into the Existing / reserved barcodes box before generation. You can use one value per line or separate values with commas.

The default conflict mode skips reserved values and continues incrementing until the requested quantity has been produced. For example, if BK000010 and BK000011 already exist, a request beginning at BK000001 can move past those identifiers and continue with the next available values. The result summary reports how many reserved values were skipped.

If you prefer to audit rather than skip, switch the conflict mode to keep the generated sequence and flag collisions. Conflicting labels are visibly marked so you can investigate before exporting or printing. Comparisons are case-insensitive, which is safer for Koha barcode planning than assuming differently cased versions are intentionally distinct.

For a full migration, export an authoritative item list from Koha first and use that data to build the reserved list. The MARC to Excel Converter can help extract Koha 952$p values from exported MARC records, while the MARC21 Validator can identify duplicate item barcodes in a MARC batch.

Understanding numeric width and leading zeroes

Libraries often use zero-padded identifiers because a fixed width is easier to sort, read and print. A six-digit suffix produces values such as 000001, 000002 and 000003. The leading zeroes are part of the identifier when you use Code 128 or Code 39, so they must also be stored in Koha.

The generator prevents the sequence from silently growing beyond its selected width. If you begin at 999998 with a width of six and request five values, only 999998 and 999999 fit. Rather than generating 1000000 as a seven-digit suffix, the tool reports that the requested quantity cannot fit. You can then increase the width or choose a different range intentionally.

Koha also includes its own label-creator barcode-range workflow. The current Koha manual notes that its barcode range feature has specific behaviour around leading zeroes. Review the official Koha cataloging and label-creator documentation when deciding whether to generate labels inside Koha or with an external planning workflow.

Export barcode values to CSV or TXT

After successful generation, you can download a UTF-8 CSV containing a single barcode column. This keeps the file simple for later mapping into a spreadsheet or migration workflow. You can also download a plain-text list or copy all generated values to the clipboard.

If the barcodes will become item records in MARC21, place the value in 952$p for the corresponding copy. The Excel to MARC Converter for Koha Libraries can map a barcode or accession-number column to 952$p when building MARC records from spreadsheet data. If you are creating records one at a time, the MARC21 Record Builder provides a smaller record-building workflow.

Do not treat the generated CSV as proof that a barcode is unused in your live Koha database. This page runs in the browser and does not log in to your ILS. The collision checker only knows the existing or reserved identifiers you paste into the tool.

Print Koha barcode labels

The result includes print controls for two, three or four label columns and an adjustable barcode height. You can show or hide the human-readable barcode value and the optional library heading. These controls are intended for quick test sheets and straightforward labels; exact commercial label-stock alignment depends on printer margins, browser print settings and the physical sheet you use.

Always print a small sample before committing hundreds of labels. Confirm that the bars are sharp, the quiet space has not been cropped, the text is legible and your real circulation scanner returns the intended identifier. Thermal printers, office laser printers and pre-cut sheet labels can produce different physical results even when the browser preview looks identical.

If you need more detailed dimensions and label CSS, use the Koha Label Template Generator. If you already have a non-sequential list of identifiers and simply need printable sheets, the Library Barcode Sheet Generator may be a better fit.

Planning barcode conventions before a migration

A migration is a good time to document barcode policy. Decide whether the existing values will be preserved, whether new acquisitions will follow the same pattern, how branch prefixes are used, and who controls the next available sequence. Avoid changing identifiers merely to make them look uniform if doing so would break labels already attached to physical items.

For new ranges, use a convention that is long enough for expected growth but short enough to remain practical. A six- or eight-digit sequence with a short prefix can support a large collection while staying well below Koha's 20-character limit. Do not encode information that changes over time unless your library is comfortable carrying that historical value permanently in the barcode.

Before a large import, use the Koha Migration Readiness Checker to review the broader preparation work. If you need a separate sequence for accession registers rather than circulation barcodes, use the Accession Number Generator instead of assuming the accession number and barcode must always be identical.

Barcode values are not the same as barcode images

A barcode value is the identifier stored in Koha. A barcode symbology is the visual encoding used to place that identifier on a label. The same logical value can sometimes be represented by more than one symbology, provided the chosen format supports its character set and length. Koha generally cares about the value returned by the scanner, not the artistic appearance of the bars.

This distinction is why the VWS Online generator validates both layers. First it decides whether the proposed Koha value fits the item field and your reserved-range rules. Then it checks whether the selected symbology can represent that value correctly. A format error is shown before printing rather than delegated to a low-level barcode library one label at a time.

Privacy and browser-side processing

Generation, range validation, collision comparison and label creation are performed in the browser. The existing/reserved barcode list is used locally by the page and is not intentionally uploaded to VWS Online as part of the generation workflow. This is useful when identifiers come from a working catalogue, but normal data-minimization rules still apply.

Do not paste patron names, card details, passwords, API credentials or unrelated personal information into a barcode utility. Item barcode values are normally operational identifiers, so provide only the data needed to detect collisions. Keep your authoritative Koha export in a protected location and use a working copy for browser-based preparation.

Common Koha barcode mistakes

• Creating values longer than Koha accepts. The generator prevents output beyond the current 20-character items.barcode limit.
• Using an alphabetic prefix with a numeric-only symbology. Choose Code 128 or Code 39 for ordinary alphanumeric library identifiers.
• Ignoring check digits. EAN-13, UPC-A and ITF-14 values need the correct final digit; this tool calculates it from the required payload.
• Letting a fixed-width sequence overflow. Increase the numeric width deliberately instead of allowing the format to change mid-range.
• Reusing an existing barcode. Paste existing or reserved identifiers and review the collision summary.
• Printing hundreds of labels without scanner testing. Verify one physical sample first.
• Assuming an accession number must equal the barcode. They can be the same by local policy, but they serve different conceptual purposes.
• Changing old identifiers unnecessarily. Preserve working barcodes during migrations unless there is a documented reason to replace them.

Frequently asked questions about the Koha Barcode Generator

Where is an item barcode stored in Koha MARC21?

In Koha's default MARC21 item mapping, the barcode is stored in 952$p and maps to the items.barcode database field.

What is the maximum Koha item barcode length?

The current Koha schema documents items.barcode as a 20-character field. This generator therefore blocks generated values longer than 20 characters.

Can I generate 1,000 Koha barcodes at once?

Yes. The revised generator supports up to 1,000 values in one run, provided the requested range fits the selected numeric width and every generated value passes the chosen format rules.

Which barcode format should I use for Koha?

Code 128 is the recommended general-purpose choice in this tool for common alphanumeric Koha item identifiers. Code 39 can also work when your values use its restricted uppercase character set. EAN-13, UPC-A and ITF-14 require numeric payloads of specific lengths.

Does the tool prevent duplicate barcodes already in my Koha database?

It can detect collisions against the existing or reserved barcode list you paste into the page. It does not connect directly to your Koha database, so it cannot discover live identifiers automatically.

Does the generator calculate EAN and UPC check digits?

Yes. It calculates and appends the check digit for EAN-13, UPC-A and ITF-14 after validating the required numeric payload length.

Can I export the generated barcodes for a Koha migration?

Yes. You can download a UTF-8 CSV with a barcode column, download a TXT list or copy all values. Map the barcode to MARC21 952$p when creating Koha item data.

Are my reserved barcode values uploaded to VWS Online?

The generator is designed to process the sequence and reserved-barcode comparison in your browser. It does not intentionally upload that list to VWS Online for generation.

Next step

Start with a small range and scan a physical test label. Once the value, symbology and printer output are confirmed, generate the full batch and export the barcode list alongside your migration or cataloguing data. For record-level checks, continue with the MARC21 Validator; for spreadsheet-to-MARC preparation, use the Excel to MARC Converter; and for a broader item-data review, combine the generator with the other VWS Online Koha and library tools rather than relying on a barcode sequence alone.