Skip to Content
Open Books for developers

Install Open Books

Install the Open Books engine and npm wrappers, add OCR and model support, and verify engine discovery in your environment.

1. Check your prerequisites

Open Books runs on Python 3.11 or newer. The npm packages also need Node.js 20 or newer. Open a terminal in your project directory and check the runtime you plan to use.

python --version
node --version
npm --version

The last two checks apply to Node.js and the npm CLI. If your system uses python3 for Python 3, use that command to create the environment below. To try a sample without a local installation, start with the browser quickstart.

2. Create and activate a virtual environment

A virtual environment keeps the engine and its dependencies together for one project. Run python -m venv .venv once. In each new terminal, activate it with the command for your shell.

source .venv/bin/activate

If shell policy blocks activation, call the environment's Python directly. On Windows, use .\.venv\Scripts\python.exe. On macOS and Linux, use ./.venv/bin/python.

3. Install for your runtime

Install the Python distribution for both the importable API and the Python CLI.

python -m pip install "openbooks==0.2.0"

4. Verify engine discovery

Run python -m openbooks engine-info and look for schema_version: "openbooks.v1" in the JSON. The layouts list shows the installed layout providers. Run python -m openbooks doctor for a readable diagnostic report. If you installed the npm CLI, openbooks engine-info should also find the engine. Check installation troubleshooting if it finds a different one.

Add scan and model support

The base Python dependency set handles structured files and text-layer PDFs. Install the scan extra for image OCR and the local typed-head model. It adds EasyOCR and PyTorch, so allocate more disk and installation time.

python -m pip install "openbooks[scan]==0.2.0"
python -m openbooks doctor --deep

See PDF and OCR for flag defaults. The Node.js wrapper enables model cross-checking for PDF and image runs by default.

Package map

DistributionPurpose
openbooks on PyPIPython engine, provider registry, Python API and CLI.
@lumeo_hq/openbooks-coreTyped runner, engine discovery and output validation.
@lumeo_hq/openbooks-statementsRunner restricted to bank statement layouts.
@lumeo_hq/openbooks-gatewaysRunner restricted to payment gateway layouts.
@lumeo_hq/openbooks-taxRunner restricted to tax and trial-balance layouts.
@lumeo_hq/openbooks-doctorProgrammatic diagnostics for Node.js.
@lumeo_hq/openbooksUnified npm CLI and Python installer.

If you're upgrading Python from 0.1, install 0.2 in a fresh virtual environment. The openbooks distribution now owns all five Python modules. Existing code can still import Params and process from openbooks.pipeline, and new code can import them from openbooks.

Run the bank CSV quickstart to confirm your environment can process a file.

View this page as Markdown