VuFind® — Importing MARC Records Guide

Overview

What is MARC and Why Import It?

MARC (Machine-Readable Cataloguing) is the global standard format that libraries use to store bibliographic records — book titles, authors, subjects, ISBNs, and more. VuFind® was built around MARC from the ground up and uses SolrMarc to transform your MARC records into a searchable Apache Solr index.

📄

MARC Record

A structured data file describing one item in your library — title, author, subject, ISBN, call number, etc. Each record has a unique ID.

🔧

SolrMarc

The import tool bundled with VuFind®. It reads your MARC file and transforms each record into a document in the Solr search engine.

🔍

Solr Index

The search engine that powers VuFind®. After importing, Solr indexes all your records so users can search and filter them instantly.

🏛️

ILS (Your LMS)

Your library management system (e.g. Koha, Symphony, Alma). This is where your records live — you export from here and import into VuFind®.

ℹ️

MARC records come in two formats: binary MARC (ISO 2709) with a .mrc extension, and MARC-XML with a .xml extension. VuFind® supports both — just make sure you use the right file extension.

How It Works

The Import Pipeline

Before diving into steps, here's the big picture of what happens when you import MARC records:

01

🏛️

Your ILS

→

02

📦

Export MARC File

→

03

⚙️

Configure

→

04

🔧

SolrMarc

→

05

🔍

Solr Index

→

06

🌐

VuFind® Live

✅

Before you start: Make sure VuFind® is installed and Solr is running (cd /usr/local/vufind && ./solr.sh start). If you haven't installed VuFind® yet, follow the Installation Guide first.

Step 01

Export Your Records from Your ILS

Before importing into VuFind®, you need to get the records out of your Integrated Library System (ILS/LMS). The exact steps differ by system — select yours below.

🐟

Koha

Open source LMS

🏛️

Other ILS

Alma, Symphony, Polaris…

🧪

Just Testing

Use sample records

🐟

Koha Export — Koha provides a built-in export script. You can run it from the command line or use the web interface.

📋

Koha — Part A

Set Environment Variables

Tell the shell where Koha is installed before running any commands.

▾

Open a terminal and set the required environment variables. Adjust paths to match your Koha installation:

terminal

export PERL5LIB=/usr/share/koha/lib:$PERL5LIB
export KOHA_CONF=/etc/koha/sites/library/koha-conf.xml

export PERL5LIB=…Adds Koha's Perl library directory to the search path so Perl can find Koha's modules. Without this, the export script will fail with "module not found" errors. Adjust the path if your Koha is installed elsewhere.

export KOHA_CONF=…Points to your Koha site's configuration file. This tells Koha which database and settings to use. The path usually follows the pattern /etc/koha/sites/<sitename>/koha-conf.xml.

⚠️

Replace library in the path with your actual Koha site name. Run ls /etc/koha/sites/ to see your site name.

📤

Koha — Part B

Run the Export Script

Export all bibliographic records to a MARC-XML file.

▾

Run Koha's export script to dump all records. Export to XML format is recommended as it handles special characters more reliably:

terminal

/usr/share/koha/bin/export_records.pl --format=xml --filename="koha.xml"

export_records.plKoha's built-in Perl script for exporting bibliographic records. It queries the Koha database and outputs records in your chosen format.

--format=xmlOutputs records in MARC-XML format. You can also use --format=marc for binary MARC (ISO 2709), which produces a .mrc file instead.

--filename="koha.xml"The output filename. The file will be created in the current directory. Choose a descriptive name — you'll reference this file in Step 3.

ℹ️

You can also export records through Koha's web interface: go to Tools → Export Data. This is easier but may time out for very large catalogues.

🔑

Koha — Part C

Configure the Koha Record ID

Tell VuFind® to use Koha's bibliographic record ID (field 999c).

▾

Koha stores its unique bibliographic ID in MARC field 999$c, not in the standard 001 field. You must tell VuFind®'s importer where to find this ID, otherwise records won't link back to Koha correctly.

Copy the local properties template and edit it:

terminal

cp /usr/local/vufind/import/marc_local.properties \
    /usr/local/vufind/local/import/marc_local.properties

cp <source> <destination>cp copies a file. We copy the template from VuFind®'s core directory into the local/ directory — always make your edits in local/ so they survive upgrades and don't touch the VuFind® core files.

Open the copied file and make sure these settings are present (add or edit as needed):

local/import/marc_local.properties

# Your institution name — appears in the "Institution" facet
institution = "My Library"

# Koha uses field 999$c for the unique bib record ID
id = 999c, first

# Optional: set a building/collection label
#building = "Main Library"

institution = "My Library"Sets a hard-coded Institution facet value applied to every record in this import. Replace My Library with your actual institution name — this is what users see in the search filters.

id = 999c, firstCritical for Koha. Tells SolrMarc to use the value in MARC field 999, subfield $c as the unique record ID. The first keyword means take only the first occurrence if there are multiple. Without this, VuFind® uses field 001 and won't match records back to your Koha catalogue.

⚠️

The id = 999c, first line may not exist in the default file — you may need to add it manually. This is the most common mistake when connecting Koha to VuFind®.

ℹ️

Every ILS is different. Check your system's documentation for its MARC export feature. The notes below apply to all systems.

📋

Export Tips

Key Rules for Any ILS Export

Follow these rules to ensure your records can be imported without errors.

▾

1. Use the right format and extension:

accepted formats
# Binary MARC (ISO 2709) — must use .mrc extension
your_records.mrc

# MARC-XML — must use .xml extension
your_records.xml

🚨

Do not export in human-readable ASCII or plain text format. SolrMarc requires binary MARC or MARC-XML. If your ILS only supports ASCII, use yaz-marcdump from the YAZ toolkit to convert it.

2. Include a unique identifier in every record:

By default, VuFind® expects the unique record ID in MARC field 001. Make sure your ILS includes the bibliographic record ID in this field. If your ILS stores the ID elsewhere (like Koha's 999$c), you'll need to configure marc_local.properties accordingly.

3. Where to find ILS-specific export documentation:

vufind export notes
https://vufind.org/wiki/indexing:marc:export_notes

The VuFind® community maintains export notes for many ILS systems including Alma, Evergreen, Horizon, Polaris, Sierra, Symphony, and more.

🧪

Just testing? VuFind® ships with sample MARC records you can use right away — no ILS needed.

📦

Sample Records

Use the Built-in Test Records

VuFind® includes sample records in its tests directory for immediate testing.

▾

VuFind® ships with sample MARC records in its test data directory. These are perfect for verifying your setup works before importing your real catalogue:

terminal — list sample records

ls /usr/local/vufind/tests/data/*.mrc

ls *.mrcLists all .mrc binary MARC files in VuFind®'s test data directory. You'll see files like test.mrc which contain a handful of sample bibliographic records ready to import.

You can import one of these directly in Step 3 — for example:

example path to use in step 3
/usr/local/vufind/tests/data/test.mrc

⚠️

Sample records may contain intentional errors since they're designed to test edge cases in VuFind®'s display logic. Use them to verify the import pipeline works, then replace with your real records.

You can also download free MARC records from the Internet Archive for a larger test dataset:

download sample records (optional)

# Internet Archive UNC MARC records (large dataset)
https://archive.org/details/unc_catalog_marc

Step 02

Configure the Importer

🗂️

Configuration

Understand the Configuration Files

Learn which files control what — before editing anything.

▾

SolrMarc uses two types of configuration files. It's important to understand their roles:

import.properties

The main config. Controls high-level settings: Solr URL, which index specification files to load, and Java options. Usually doesn't need changing.

marc_local.properties

The index spec you customise. Defines how MARC fields map to Solr fields — institution name, ID field, building, collection, etc.

Here's where these files live in a standard VuFind® installation:

/usr/local/vufind/ import/ import.properties ← main config (read-only reference) marc.properties ← default field mappings (don't edit) marc_local.properties ← your customisations go here local/ import/ marc_local.properties ← ✓ BEST: put your copy here

ℹ️

Always put your custom marc_local.properties in /usr/local/vufind/local/import/. Files in local/ take priority over core files and are preserved through VuFind® upgrades.

✏️

Configuration

Edit marc_local.properties

Set your institution name and verify the Solr URL is correct.

▾

If you haven't already done so in Step 1, copy and edit the local properties file:

terminal
# Create the local import directory if it doesn't exist
mkdir -p /usr/local/vufind/local/import

# Copy the template
cp /usr/local/vufind/import/marc_local.properties \
   /usr/local/vufind/local/import/marc_local.properties

# Open it in nano to edit
nano /usr/local/vufind/local/import/marc_local.properties

mkdir -pCreates the directory (and any parent directories) if it doesn't already exist. The -p flag prevents errors if the folder already exists.

nano <file>Opens the file in the nano text editor. Use arrow keys to navigate. Press Ctrl+O to save and Ctrl+X to exit.

The key settings to review and customise:

marc_local.properties — key settings

# ── Required: your institution name ──
institution = "University of Example"

# ── Optional: collection or building facet ──
#collection = ""
#building = "Main Library"

# ── Koha only: use 999c as the unique record ID ──
# id = 999c, first

# ── Other ILS: leave id commented out to use default MARC 001 ──

institution = "…"Sets the institution name that appears in VuFind®'s Institution facet. Every record imported with this config will carry this label. Wrap the value in quotes.

building = "…"Optional — tags records with a building/branch label useful in multi-branch libraries. Remove the # at the start of the line to enable it.

Next, verify the Solr URL in import.properties is correct (usually no change needed):

import.properties — solr url
# Default Solr URL — should be correct for a standard install
solr.hosturl = http://localhost:8983/solr/biblio/update

Step 03

Run the Import

⚠️

Make sure Solr is running before starting the import. Run cd /usr/local/vufind && ./solr.sh start if it isn't already. Importing with Solr stopped will fail silently.

▶️

Import

Run import-marc.sh

The main import command — point it at your MARC file and run.

▾

Navigate to your VuFind® directory and run the import script with your MARC file:

terminal — basic import

cd /usr/local/vufind
./import-marc.sh /path/to/your_records.mrc

cd /usr/local/vufindMove your terminal into VuFind®'s installation directory. The import script must be run from this directory.

./import-marc.sh <file>Runs VuFind®'s MARC import wrapper script. It launches SolrMarc, reads your MARC file record by record, transforms each one using your properties files, and sends them to Solr. Replace /path/to/your_records.mrc with your actual file path.

ℹ️

For MARC-XML files use the same command — just point it at a .xml file instead of .mrc. SolrMarc auto-detects the format from the extension.

terminal — multiple files (VuFind® 9.1+)

cd /usr/local/vufind
./import-marc.sh file1.mrc file2.mrc file3.mrc

./import-marc.sh file1.mrc file2.mrc …From VuFind® 9.1 onwards, you can pass multiple filenames in one call. SolrMarc loads all of them in sequence. This is faster than running the script once per file because it avoids the Java startup overhead on each run.

💡

You can also use shell wildcards: ./import-marc.sh /path/to/records/*.mrc to import every .mrc file in a directory at once.

terminal — with custom properties file

cd /usr/local/vufind
./import-marc.sh -p /usr/local/vufind/local/import/import.properties \
    your_records.mrc

-p <path/to/import.properties>The -p switch overrides which SolrMarc configuration file to use. When omitted, the script automatically uses local/import/import.properties if it exists, otherwise falls back to import/import.properties. Use -p when you have multiple configurations for different record sets.

⏱️

Import time: Small collections (a few thousand records) finish in minutes. Large catalogues with hundreds of thousands of records can take hours or even days. Run the import in a screen or tmux session so it keeps running if you disconnect.

run in background with screen (optional)
# Start a detachable terminal session
screen -S marc-import

# Then run the import as normal — press Ctrl+A then D to detach
cd /usr/local/vufind
./import-marc.sh your_records.mrc

# Reattach later to check progress
screen -r marc-import

screen -S marc-importscreen creates a persistent terminal session that keeps running even if your SSH connection drops. The -S flag names the session so you can find it again easily. If screen isn't installed, run sudo apt-get install screen first.

Step 04

Restart VuFind® / Solr

🔄

Restart

If Records Don't Appear — Restart Solr

Sometimes Solr needs a nudge to make newly imported records visible.

▾

After importing, open your VuFind® site in a browser. If the new records don't appear in search results within a minute or two, restart Solr:

terminal — restart solr

cd /usr/local/vufind
./solr.sh stop
./solr.sh start

./solr.sh stopGracefully shuts down the Solr search engine. Solr writes any pending changes to disk before stopping, so no data is lost.

./solr.sh startStarts Solr again. On startup it loads all indexed records into memory and makes them searchable. After this, your imported records should appear in VuFind® search results.

✅

After restarting, visit your VuFind® site and try a search. You should see your catalogue records in the results. If you imported sample records, search for something generic like "library" or "history".

Step 05

Optimize Your Solr Index

⚡

Optimization

Run Solr Index Optimization

Improves search speed and enables the spellchecker — do this after every bulk import.

▾

After a large import, it's good practice to optimize the Solr index. This merges index segments for faster queries and regenerates the spelling index (which powers VuFind®'s "Did you mean?" suggestions).

terminal — trigger solr optimization

cd /usr/local/vufind
php public/index.php util/optimize

php public/index.php util/optimizeCalls VuFind®'s built-in optimize utility, which sends an optimization request to Solr. Solr merges its index segments into a single segment, resulting in faster read performance. It also rebuilds the spellcheck index. This may take several minutes on large collections — don't interrupt it.

ℹ️

Optimization is optional but highly recommended after any full reimport or large batch update. For small incremental imports (a few hundred records), it's usually not necessary.

🎉

Import complete! Your MARC records are now indexed and searchable in VuFind®. Continue with the advanced sections below to handle authority records, multiple library collections, or automated imports.

Advanced

Importing Authority Records

🎓

Authority Records

Import Name & Subject Authority Data

Optional — improves subject heading consistency and enables authority-driven search enhancements.

▾

VuFind® has a separate authority index for name and subject authority records (e.g. Library of Congress authority files). Importing these enables better subject heading cross-references and search enhancements.

Use the dedicated authority import script — it works exactly like import-marc.sh but targets a different Solr core:

terminal — import authority records

cd /usr/local/vufind

# Standard authority records (ID in 010 field — LC format)
./import-marc-auth.sh your_authority_file.mrc

# ILS-exported authority records (ID in 001 field)
./import-marc-auth.sh your_authority_file.mrc marc_auth_ils.properties

./import-marc-auth.shThe authority record import script. It uses import/import_auth.properties for its configuration and import/marc_auth.properties for field mappings — a separate set from the bibliographic import.

marc_auth_ils.propertiesAn optional second parameter that specifies additional mapping overrides. Use marc_auth_ils.properties when your authority records came from an ILS export that stores the unique ID in field 001 rather than the standard Library of Congress 010 field.

ℹ️

Authority records are optional. Most beginner setups work fine without them. Add them later once your bibliographic import is working correctly.

Advanced

Multiple Libraries / Collections

If you're importing records from multiple branches or institutions, you can tag each set with a different Institution or Building label by creating separate configuration files for each.

🏗️

Multi-Library

Step 1 — Create Per-Library Index Spec Files

One small properties file per institution, each setting a different label.

▾

Create a separate index specification file for each library. These only need to contain the settings that differ — everything else is inherited from marc_local.properties:

terminal — create spec files

# Create spec for Library 1
echo 'institution = "Library 1"' > \
    /usr/local/vufind/local/import/marc_library1.properties

# Create spec for Library 2
echo 'institution = "Library 2"' > \
    /usr/local/vufind/local/import/marc_library2.properties

echo '…' > filenameecho outputs text to the terminal; the > operator redirects that output into a file, creating the file if it doesn't exist. This is a quick way to create a small single-line config file without opening a text editor.

🔗

Multi-Library

Step 2 — Create Per-Library import.properties Files

Chain together the spec files so each library's config loads its own label.

▾

Copy the main import.properties once for each library and edit the solr.indexer.properties line to chain in the library-specific spec:

terminal — copy and edit for library 1

cp /usr/local/vufind/import/import.properties \
   /usr/local/vufind/local/import/import_library1.properties

nano /usr/local/vufind/local/import/import_library1.properties

Inside the file, find and update the solr.indexer.properties line:

import_library1.properties — edit this line

# Chain the spec files — last file wins for duplicate settings
solr.indexer.properties = marc.properties, marc_local.properties, marc_library1.properties

solr.indexer.properties = a, b, cA comma-separated list of index specification files to load in order. Later files override earlier ones for any duplicate settings. Here, marc_library1.properties is last, so its institution value overrides the one in marc_local.properties. Repeat this pattern for each library.

Repeat for Library 2 (and any others), changing the filename and spec file reference accordingly.

▶️

Multi-Library

Step 3 — Run Each Import with -p Switch

Use a different -p config file for each MARC file you import.

▾

Now run the import once per library, passing the correct configuration each time:

terminal — import all libraries

cd /usr/local/vufind

# Import Library 1 records
./import-marc.sh -p /usr/local/vufind/local/import/import_library1.properties \
    /path/to/library1.mrc

# Import Library 2 records
./import-marc.sh -p /usr/local/vufind/local/import/import_library2.properties \
    /path/to/library2.mrc

-p <import_library1.properties>Tells the import script to use Library 1's configuration. All records from library1.mrc will be tagged with Institution = "Library 1". Users can then filter search results by institution using VuFind®'s facets.

✅

After importing all libraries, run optimization once: php public/index.php util/optimize. Users will then see an Institution facet to filter results by library.

Advanced

Full Text Indexing

📝

Full Text

Index Full Text from URLs in MARC Records

Optional — lets users search inside document content, not just metadata.

▾

VuFind® can harvest and index the full text of documents if your MARC records contain URLs (e.g. in field 856). This is disabled by default and requires an additional tool to be installed first.

Step 1: Install a full-text extraction tool (Apache Tika recommended):

terminal

sudo apt-get install default-jre
wget https://downloads.apache.org/tika/tika-app-2.9.2.jar -O /usr/local/vufind/import/tika-app.jar

Step 2: Enable full text in marc_local.properties by uncommenting the fulltext line:

marc_local.properties — enable full text

# Remove the # at the start of this line to enable full text indexing:
fulltext_str_mv = FullTextExtractor(856u, "org.solrmarc.index.extractor.impl.fulltext.FullTextExtractor")

⚠️

Full text indexing dramatically increases import time and index size. Each document URL must be fetched and processed. Only enable this if your records contain accessible URLs and you have disk space and time to spare.

Automation

Schedule Automated Imports

🕐

Cron

Keep Your Index Up to Date with Cron Jobs

Run imports automatically on a schedule so VuFind® always reflects your latest catalogue.

▾

For production use, set up a cron job to re-export and re-import records automatically. Open your crontab and add an entry:

terminal — open crontab

crontab -e

crontab -eOpens your user's cron job list in a text editor. Each line defines a scheduled task: minute hour day month weekday command. * means "every".

Add one of these example schedules depending on how often your catalogue changes:

crontab entries — add these lines

# Run a full reimport every night at 2:00 AM
0 2 * * * cd /usr/local/vufind && ./import-marc.sh /data/exports/catalogue.mrc >> /var/log/vufind-import.log 2>&1

# Optimize the index every Sunday at 3:00 AM (after nightly import)
0 3 * * 0 cd /usr/local/vufind && php public/index.php util/optimize >> /var/log/vufind-optimize.log 2>&1

0 2 * * *Cron schedule: run at minute 0, hour 2, every day of the month (*), every month (*), every day of the week (*). Translates to: every night at 2:00 AM.

>> /var/log/vufind-import.log 2>&1Redirects both standard output and error messages to a log file. This lets you check what happened after the job runs without being present. View logs with cat /var/log/vufind-import.log.

0 3 * * 0Runs at 3:00 AM every Sunday (0 = Sunday). Schedule optimization after the import completes — hence 1 hour later on a weekly basis to avoid slowing daily imports.

ℹ️

Make sure your Koha export script or ILS export runs before the VuFind® import in the schedule. You may need to chain the export and import commands, or schedule the export earlier (e.g. 1:00 AM export, 2:00 AM import).

🎉

You're done! Your MARC records are imported, your index is optimized, and your imports are automated. VuFind® will now keep your search results current with your library catalogue automatically.

Contents

Importing MARC Records
into VuFind®