The Koha OPAC - Open Public Access Catalog

Koha Library Software

When my father-in-law died some years ago he left us a small, but very eclectic library. He was a painter, so there are loads of books on painting and painters, but also art and antiquities in general. Add to that novels, poetry and then there are our own books.

All in all there are at least a thousand books, and maybe twice that. We don’t know yet.

My wife is a librarian, so she asked to setup some system to register them all.

After a bit of searching I found Koha – an open source library management system which has a vibrant and active community of users and developers.


This kind of software is not straight-forward. You need technical knowledge, in this case Linux, Apache, MariaDB and Perl, and you need to understand a good deal about cataloguing, bibliographic metadata, Z39.50 and how libraries work in general.

A first attempt at installing Koha on an existing VPS, which I used for WordPress web sites, failed with all sorts of Debian dependency issues, so I opted for a new VPS with a fresh install of Debian 11, as per the Koha recommendation.

Firstly, if you want Koha to work, follow the installation instructions slavishly. They’re very good.

Secondly, don’t be tempted by the ‘–letsencrypt’ option to the koha-create program. It doesn’t work, and it is far easier to edit the Apache configuration afterwards to use the ‘md’ Apache module for web site certificates.

Thirdly, when configuring the first instance (a Koha installation can run several instances for different libraries) read every point carefully, and if in doubt about something, check it. You might not use all those “Typical patron categories” but it is far easier to delete them than to setup you own from scratch.

Fourthly, when you have the instance running, enter the staff interface, go to “Koha Administration” and then “MARC Bibliographic framework test” and fix the errors. At least in my case, a fresh install had framework errors, and not trivial ones either. It took me a while a a few attempts.

Bibliographic Frameworks

Bibliographic frameworks are not just different ways of displaying a MARC record. They decide which fields are saved for a record. If you switch a record to a simpler framework and back again, you lose data.

You need to get the bibliographic frameworks right before you enter or import lots of records.

A freshly installed system has a default framework, an “Acquisition framework” which is very simple, and optionally a “Fast Add Framework” which is even simpler. The latter doesn’t even save the ISBN number.

Within “Administration > MARC frameworks” individual frameworks can be added, deleted, modified, exported and imported.

Export the default framework, add a new one, and import the data from the default framework into it. Then modify that local framework and use that for you records.

In my case the default framework had lots of issues that I had to fix.

Many fields are mandatory, so it can be really hard to get a record to save without errors. That led me initially to use the other pre-installed frameworks, which cause my records to lose lots of fields I didn’t want to lose.

If you want to make many changes to a framework, export it as an OpenOffice spreadsheet file, modify that in LibreOffice and reimport it again afterwards. Keep backups of the spreadsheets, because an import error will leave you with empty and useless frameworks.

Importing MARC records

The easiest way of getting data into your system is to import the MARC records from other libraries who’ve already done the hard and difficult work of cataloguing the books.

Get a barcode scanner, they’re as cheap as €20, scan the ISBN and you’ll find the MARC record in a jiffy. At least in theory.

The common protocol for this is Z39.50.

It is not easy to find the parameters for Z39.50 servers. There are many lists online, but much of the data is not current and often not valid.

In Koha go to “Administration > Z39.50/SRU servers” to setup you preferred Z39.50 servers. It is fairly straightforward if you can find servers that work with public access.

Servers like the Italian National Library System (SBN) have public access and serves the records in UNIMARC so I had absolutely no issues with them, which is nice as most of our books are published in Italy or are in Italian.

If I searched on LIbrary of Congress in the USA, or on the British Library (you have to ask for access) I got results, but no titles, authors or any other data were displayed. If I imported the records, they were mostly empty.

MARC flavours

There are several flavours of MARC records. The major ones are MARK21 (or USMARC) and UNIMARC, but in Europe most countries seem to use some locally modified format of one or the other.

We’re in Italy, so I configured our Koha instance to use UNIMARC.

The problem with LoC and BL is, I discoved after a while, one of different MARC flavours. Our instance uses UNIMARC while LoC and BL use MARC21.

Koha doesn’t convert from one format to the other when you import a record. Koha does ask you when you configure a Z39.50 server, which format the server uses, but it still doesn’t convert the data.

This took me a while.

MARC records are not XML, but in the X39.50 server configuration there was a fields for custom XSLT files. Maybe Koha worked internally with MARCXML which is an XML representation of a MARC record?

Apparently lots of libraries use a program called MarcEdit to do this conversion between MARC flavours. It is written by a Terry Reese, and lo and behold if he didn’t have such “MARC21 to UNIMARC” XSLT files on Github.

I downloaded his marc21xml2unimarc.xsl file, copied it to my VPS, entered the pathname in the Z39.50 server configuration, and suddenly my imports from LoC and BL worked perfectly.

Cataloguing workflow

Once everything is working you need to get data into your system. Fortunately it’s not that hard.

Go to “Cataloguing > New from Z39.50”, scan the ISBN number on the back of the book, and pick best record for your edition of the book from the results. If your bibliographic framework is not too obnoxious, a few clicks and you have the record saved.

Older or rarer books without ISBN numbers are a bit harder to find, but often a combination of title, author and year published will find them. We’ve even found Venetian tourist guides for the 1880s like that.

Koha can allocate barcode numbers for all items automatically. I have bought sheets of labels and preprinted the barcodes, so all our books now have a barcode on the inside back cover. With the barcode scanner we can locate a book in no time, or just figure out on which shelf it belongs.


It’s been a bit of a fight installing and configuring Koha, but having a such a system, even just for a private library, is very useful.


One response to “Koha Library Software”

  1. MR RANJEET avatar

    Thank you for sharing such an informative and well-crafted blog post. The clarity of your writing and the logical flow of your arguments made it a pleasure to read. To gain a deeper understanding, click here.

Leave a Reply

Your email address will not be published. Required fields are marked *