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
What you are installing
terbium has three layers, and only the first is required:
- 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.
- 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.
- 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"inpyproject.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
PATHfor 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,--htmland--opencommand line flags - document classification and the
transactionandresumeschemas - the image file adapter (
png,jpg,jpeg,webp,tiff) terbium.classify,terbium.records_to_csv,terbium.render_htmlandterbium.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.