Calamari: line based OCR and HTR on top of OCRopy and Kraken

A line recogniser built on OCRopy and Kraken

Calamari is described as a line based ATR engine based on OCRopy, and the README adds that it is an OCR engine based on OCRopy and Kraken using Python 3. The word that matters is line. Calamari is the recognition stage: something upstream has already decided where the text lines are, and Calamari's job is to turn each line image into characters.

That framing explains the shape of the package. The project keywords in `pyproject.toml` are OCR and HTR, the classifiers list `Environment :: Console` and `Environment :: GPU :: NVIDIA CUDA` as supported environments, and the intended audiences are developers, education and science or research. The package is declared as a library, `Topic :: Software Development :: Libraries :: Python Modules`, with a line based engine sitting underneath the tooling.

The tooling is the part most users meet. The `pyproject.toml` declares a set of console entry points, one per task:

[project.scripts]
calamari-eval = "calamari_ocr.scripts.eval:run"
calamari-predict = "calamari_ocr.scripts.predict:main"
calamari-resume-training = "calamari_ocr.scripts.resume_training:main"
calamari-train = "calamari_ocr.scripts.train:run"
calamari-cross-fold-train = "calamari_ocr.scripts.cross_fold_train:run"
calamari-predict-and-eval = "calamari_ocr.scripts.predict_and_eval:run"

Predict, evaluate, train, resume training, cross-fold training and a combined predict and evaluate run are separate commands, and the naming maps onto a machine learning workflow rather than onto a single product.

The project also asks to be cited. The reference is Wick, Reul and Puppe, `Calamari - A High-Performance Tensorflow-based Deep Learning Package for Optical Character Recognition`, published in Digital Humanities Quarterly 14(1) in 2020, which is the artifact to cite if the work ends up in a research project.

Install from PyPI, then read the documentation rather than the README

Installation is a single command, and the README is honest about where the rest of the information lives.

pip install calamari-ocr

The package is on PyPI under the name `calamari-ocr`, while the importable distribution name in `pyproject.toml` is `calamari_ocr`, which is the usual difference between the PyPI name and the Python module name. The console scripts listed in the previous section land on your path as part of that install, so `calamari-predict` and `calamari-train` are available straight away.

The README then does something unusual and, in a reviewer's view, sensible: it points at the hosted documentation at `calamari-ocr.readthedocs.io` for further instructions, points at the same place to learn how to use Calamari from the command line, and points there again for the API. Almost nothing about actual usage is in the README, so the documentation is not a supplement here, it is the manual.

The repository reflects that arrangement. The `docs/` directory holds the documentation sources, and `.readthedocs.yaml` configures the build for the hosted site. The `resources/` directory holds the logo and the preview image, and `MANIFEST.in` is what tells setuptools which of those non-Python files to include in the source distribution.

So a first contact with Calamari looks like this: install the package, install or fetch a model, and read the documentation sections on the command line and on the API before writing anything.

TensorFlow 2.4 and a forked TFAIP are the real install cost

The dependency list is short in lines and heavy in bytes, and it is the first thing to look at before planning an installation.

edit_distance
h5py
importlib_resources ; python_version < '3.10'
lxml
python-bidi~=0.4.2
tensorflow>=2.4.0
ocrd-fork-tfaip>=1.2.7
xlsxwriter

`tensorflow>=2.4.0` is the headline, and it means the environment carries a deep learning framework whether or not you train anything. `ocrd-fork-tfaip>=1.2.7` is a fork, which matters for supply chain review and for future maintenance: a fork is a dependency the upstream project controls, and its version numbering is independent of the public package it was forked from. `h5py` points at the HDF5 model format, `lxml` at XML handling, `xlsxwriter` at spreadsheet output, `python-bidi` at bidirectional text, `edit_distance` at the evaluation metric, and `importlib_resources` is pulled in only for Python below 3.10, as a backport of the standard library's `importlib.resources`.

The Python floor is declared separately in `pyproject.toml`, where `requires-python` is `>=3.7`, and the version and the dependency list are both declared as dynamic, meaning they are filled in at build time rather than written in the file.

For GPU work there is a second path. The repository carries `environment_master.yml` and `environment_master_gpu.yml`, two environment files, one of which is the GPU variant, and the package classifiers list NVIDIA CUDA as a supported environment. A deployment on a GPU box has to pick the right environment file rather than install from the plain requirements list and hope.

None of this is unusual for a deep learning OCR project, but it is the reason the install is not a lightweight one, and it belongs in any evaluation that cares about image size and startup time.

Pretrained models live in two other repositories

Calamari does not ship its models in the package. They live in two separate repositories, `calamari_models` and `calamari_models_experimental`, and the current releases with individual model tarballs are reachable through the release pages of those repositories, at the `2.1` tag for the main one and `v0.0.3` for the experimental one.

The consequence is a two-repository version question. The code lives in one repository with its own release tags, and the model weights live in another with different ones, and the two numbering schemes are unrelated. Installing the newest Calamari and pointing it at an old model tarball is exactly the kind of mismatch that produces confusing accuracy numbers rather than a clear error.

The split has a rational side. Model weights are large, they change far less often than the code, and keeping them out of the Python package keeps the wheel small and lets a team host its own models. The experimental repository, kept separate from the main one, lets new models be tried without becoming the default.

For an adopter, the practical question is which model repository to mirror, which tag to pin, and whether that tag is compatible with the Calamari release in use. The documentation is the place where the model compatibility is described, because the README only links to the repositories and their release pages.

Versioning from git tags, linting with black, CI on GitLab

The build and the repository hygiene are set up in a way that says who maintains this.

The build backend is setuptools with the `setuptools_scm` plugin, and the plugin is what produces the version number:

[build-system]
requires = [
         "setuptools>=42",
         "setuptools_scm[toml]",
         "wheel",
]  # PEP 508 specifications.
build-backend = "setuptools.build_meta"

Because the version is dynamic and derived from the repository state, the version of an installed package follows the git tag it was built from. That is why the release list contains a version like `2.3.0.post1` alongside `2.3.0`, and it is a reason to build from a tag rather than from an arbitrary branch, because an untagged build has no meaningful version to report.

The quality gates are visible in the repository root. `.flake8` configures the linter, `.pre-commit-config.yaml` wires the local hooks, and the workflow badges in the README name the checks: a Python test workflow, a black lint workflow, and a workflow that uploads the Python package. Coverage is tracked through codecov, with the README badge linking to a codecov page for the bertsky/calamari repository. There is a `.gitlab-ci.yml` as well as a `.github/` directory, so the project runs on two CI systems, and `.lgtm.yml` carries the configuration for a code quality scanner.

The `pyproject.toml` classifies the project as `Development Status:: 5 - Production/Stable`, which is a self-declaration worth taking with the appropriate amount of salt, but it is consistent with a package that has a stable release line and a fixed public API.

Where Calamari is the wrong tool

Three constraints follow directly from the design, and a fourth comes from the release history.

The scope constraint is the line. Calamari is a line based engine, so it expects text that has already been segmented into lines. A team with whole page images and no segmentation step needs something else, or needs to build that step itself.

The dependency constraint is the one described earlier. TensorFlow 2.4 or later plus a forked TFAIP package is a heavy environment, and the two environment files in the repository show that GPU and CPU setups are separate concerns. A lightweight service that has to start quickly and run on a small machine is not the target.

The model constraint is that the weights are external, with a version you have to choose and pin. Teams that need a reproducible, auditable model have to mirror the model repository internally and freeze a tag.

The release gap is the fourth. The recent releases are v2.3.1 from 2024-11-12, v2.3.0.post1 and v2.3.0 from 2024-10-01, while the last push to the repository was on 2026-06-23. The project is not archived and the work continues, but a version published two years ago is what most installations will be running, so anyone considering the tip of the branch should expect to test it themselves.

The alternative approach is to skip the Calamari layer and use OCRopy or Kraken directly, since Calamari is described as being based on both of them. The difference is that Calamari adds the deep learning line recognition model and the surrounding workflow, with training, cross-fold training, evaluation and prediction scripts in one place and pretrained models published for download. Going straight to the base engines means less to install and no model repository to track, at the cost of building the training and evaluation pipeline yourself.

Editorial conclusion

Calamari fits a research or digitisation team that recognises lines of text with a deep learning model, needs the training and cross-validation scripts that come with it, and is willing to pull in TensorFlow and a separate model repository. It is the wrong choice for a service that must start quickly, because the dependency set includes TensorFlow 2.4 or later and a forked TFAIP package, and for anyone who needs a model that is guaranteed to match the installed code, because the pretrained models are versioned in other repositories. Before adopting it, read `requirements.txt` against the environment you have to run, check that the `calamari_models` release tag you pin matches the Calamari release you install, and read the API section of the documentation, since the README itself deliberately points there for anything beyond the install command.

Frequently asked questions

Official sources

1. Calamari-OCR/calamari on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases