Docs / Overview

Installation

scanlayer is a Python package that wraps two external binaries: Tesseract (required) and poppler (only if you feed it native PDF files). Get those two right first; the Python side is a normal pip install.

Requirements

Requirement	Needed for
Python 3.9+	Everything. The codebase uses `from __future__ import annotations` and PEP 604 unions.
Tesseract OCR	All OCR. Installed separately, see below.
pytesseract, Pillow, reportlab, opencv-python-headless, numpy, pdf2image	Python dependencies, installed automatically by `pip install scanlayer` (or from `requirements.txt` when running from a source checkout).
poppler (`pdftoppm`/`pdfinfo` on PATH)	Only if a source file is a native `.pdf` (rasterized via `pdf2image`).

requirements.txt pins none of these to an exact version Only lower bounds are set (e.g. Pillow>=10.0.0). If you need a fully reproducible environment, freeze a lockfile yourself after the first install.

Installing Tesseract

Tesseract is a compiled binary, not something pip can install for you:

OS	Command
Debian / Ubuntu	`apt install tesseract-ocr`
macOS (Homebrew)	`brew install tesseract`
Windows	The tesseract-ocr build

scanlayer looks for the binary automatically, in this order:

the TESSERACT_CMD environment variable
a binary bundled next to the package under bin/tesseract/ (see Bundling Tesseract)
the system PATH, then a short list of common per-OS install locations

If none of those find it, point at it explicitly:

bash

export TESSERACT_CMD=/path/to/tesseract     # macOS/Linux
set TESSERACT_CMD=C:\path\to\tesseract.exe  # Windows

pythonscript.py

import scanlayer
scanlayer.configure(tesseract_cmd="/path/to/tesseract")

osd.traineddata matters Automatic orientation detection (rotating an upside-down or sideways page before OCR) needs osd.traineddata in your tessdata directory, alongside your language packs. It ships with most Tesseract installs by default, but a minimal/custom tessdata directory can be missing it: if orientation correction silently stops working, check for this file first.

poppler (PDF input only)

Skip this section entirely unless you plan to feed scanlayer a native .pdf file directly (it gets rasterized page-by-page before OCR). Everyday image inputs (jpg, png, tiff…) never need it.

OS	Command
Debian / Ubuntu	`apt install poppler-utils`
macOS (Homebrew)	`brew install poppler`
Windows	Download a poppler release and add its `bin/` folder to `PATH`

pip install pdf2image is not enough pdf2image is a thin wrapper around the pdftoppm/pdfinfo binaries that ship with poppler; it does not vendor them. Without poppler on PATH, scanlayer raises a DependencyError naming exactly this, instead of letting a cryptic subprocess traceback surface.

Option A, install from PyPI (recommended)

bash

pip install scanlayer

Installs the scanlayer console command and makes import scanlayer importable from anywhere on the machine. This is the normal path for using scanlayer in a project; it pulls in all Python dependencies automatically.

Option B, run from a source checkout, no install

bash

git clone https://github.com/Hyacinthe-primus/scanlayer.git
cd scanlayer
pip install -r requirements.txt
python -m scanlayer invoice.jpg -o invoice.pdf

No console command and no global import scanlayer, but everything else behaves identically. Every CLI example in this documentation works from a checkout, just replace scanlayer with python -m scanlayer. This path (and the editable pip install -e . variant) is meant for working on scanlayer itself; see Contributing if that is what you are doing.

Verifying the install

bash

scanlayer --help

pythonverify.py

import scanlayer
print(scanlayer.__version__)
print(scanlayer.get_settings()["tesseract_cmd"])

The second library snippet prints the Tesseract path scanlayer actually resolved, which is useful for confirming which binary it found before running a real conversion.