Skip to content
terbium

terbium / Get started

Installation

Install terbium from PyPI or from source, add the optional AI provider extras, and set up Tesseract for OCR on images.

On this page
  1. What you are installing
  2. Requirements
  3. Names: install terbium-parse, import terbium
  4. Install from PyPI
  5. Upgrading from 0.9.7
  6. Install from source
  7. Optional AI extras
  8. Optional: Tesseract for OCR
  9. Check the install

What you are installing

terbium has three layers, and only the first is required:

  1. The package. Pure Python on top of four libraries that read the file formats. It needs no network and no key, and it does all the table, catalogue, invoice and resume work on its own.
  2. A provider software development kit (SDK), optional. Only the artificial intelligence (AI) lane uses one. Each provider is a separate extra, so you install only the one you will call.
  3. Tesseract, optional. A local optical character recognition (OCR) program. It is the only way terbium gets words out of an image file or a scanned page without a model.

Everything optional is detected at run time. Leave it out and that lane is off; nothing else changes.

Requirements

  • Python 3.9 or newer (requires-python = ">=3.9" in pyproject.toml).
  • Core dependencies, installed automatically: PyMuPDF (1.24 or newer), python-pptx (0.6.23 or newer), openpyxl (3.1 or newer) and Pillow (10.0 or newer).
  • Optional: a local Tesseract binary on your PATH for OCR of image files and image-only Portable Document Format (PDF) pages.
  • Optional: an application programming interface (API) key for one AI provider if you want the AI lane.

Names: install terbium-parse, import terbium

What Name
Python Package Index (PyPI) distribution terbium-parse
Python import import terbium
Command line tool terbium

These come from pyproject.toml (name = "terbium-parse", [project.scripts] terbium = "terbium.cli:main") and the package directory src/terbium/. terbium_parse is the same distribution name in normalized form. The project called terbium on PyPI is unrelated, so do not install it.

Install from PyPI

pip install terbium-parse

This installs 2.0.0, released on 2026-10-26 and the version these docs describe. Check what you have with:

terbium --version          # terbium 2.0.0

The same version is a GitHub release, with the wheel and the source distribution (sdist) attached.

Upgrading from 0.9.7

Before 2.0.0, PyPI served 0.9.7 (uploaded July 2026). Version 0.10.0 (2026-09-30) was published on GitHub only, so on PyPI 2.0.0 follows 0.9.7, and upgrading brings everything 0.10.0 added:

pip install --upgrade terbium-parse

The 0.10.0 features missing from 0.9.7 include:

  • the --type, --html and --open command line flags
  • document classification and the transaction and resume schemas
  • the image file adapter (png, jpg, jpeg, webp, tiff)
  • terbium.classify, terbium.records_to_csv, terbium.render_html and terbium.render_terminal_table
  • the OpenAI, Kimi and Grok providers (0.9.7 supports Anthropic and Gemini)

2.0.0 follows 0.10.0 directly. The jump in the version number is not an API break: code written for 0.10.0 runs unchanged. See Changelog and status for the full history.

Install from source

Clone the repository for development:

git clone https://github.com/velofy/terbium.git
cd terbium
pip install -e ".[dev]"

An editable install needs a pip recent enough to support pyproject.toml builds. The pip 21.2 that ships with the macOS system Python 3.9 refuses pip install -e .; run python -m pip install --upgrade pip first.

Optional AI extras

The AI lane is opt-in, and terbium runs fully without any of these packages. Each extra installs one provider SDK:

pip install "terbium-parse[anthropic]"   # Claude (preferred)
pip install "terbium-parse[openai]"      # GPT
pip install "terbium-parse[kimi]"        # Kimi, through the OpenAI-compatible client
pip install "terbium-parse[grok]"        # Grok, through the OpenAI-compatible client
pip install "terbium-parse[gemini]"      # Gemini
pip install "terbium-parse[ai]"          # all of the above

The openai, kimi and grok extras exist from 0.10.0, and they need openai>=1.45. 0.9.7 defines only anthropic, gemini, ai and dev.

Then set a key in the environment or pass it to terbium.AI(...). See AI lane and routing.

A key without its SDK does not raise an error inside terbium.parse: the model call fails quietly and the hard tables stay as they were. Install the extra for every provider whose key you set. See Troubleshooting and limits.

Optional: Tesseract for OCR

terbium calls Tesseract through PyMuPDF’s built-in bridge, so no extra Python package is needed. It checks for a tesseract binary on PATH and, if it finds none, skips OCR silently. Without Tesseract:

  • image files parse to a page with no words, so no records come out, and no message is printed;
  • image-only PDF pages stay unread, and terbium reports them.

Install Tesseract with your system package manager (for example brew install tesseract on macOS or apt install tesseract-ocr on Debian and Ubuntu).

PyMuPDF’s bridge needs the TESSDATA_PREFIX environment variable to point at Tesseract’s language data. If it is unset, terbium looks in the usual Homebrew, MacPorts and Linux locations (for example /opt/homebrew/share/tessdata and /usr/share/tessdata) and sets it for you. If your data lives elsewhere, set TESSDATA_PREFIX yourself.

Check the install

terbium --version          # terbium 2.0.0
python -c "import terbium; print(terbium.supported_extensions())"
python -c "from terbium.layout import ocr; print(ocr.available())"   # True if Tesseract works

On 2.0.0 the second command prints:

['csv', 'jpeg', 'jpg', 'pdf', 'png', 'pptx', 'tif', 'tiff', 'tsv', 'webp', 'xlsm', 'xlsx']

2.0.0 imports PyMuPDF as pymupdf, so with PyMuPDF 2.0 these commands no longer print the FutureWarning about the deprecated fitz API that 0.9.7 and 0.10.0 printed. See Troubleshooting and limits.

Next: Quickstart.