scanlayer
Docs / Reference
CLI Reference
Every flag scanlayer accepts, and what each exit code means.
For task-oriented walkthroughs, see Examples.
Usage
bash
scanlayer INPUT [INPUT ...] [-o OUTPUT] [options]bash
# Language and DPI
scanlayer invoice.jpg -o invoice.pdf --lang fra --dpi 300
# Verbose logging
scanlayer invoice.jpg -o invoice.pdf --verbose
# PDF metadata + JPEG quality
scanlayer invoice.jpg -o invoice.pdf --jpeg-quality 90 --title "Invoice 2024"
# Batch conversion: multiple inputs, output must be a folder
scanlayer *.jpg -o ./converted/
# Export raw OCR result instead of a PDF
scanlayer invoice.jpg -o invoice.json --format json
# Debug overlay alongside any format
scanlayer invoice.jpg -o invoice.pdf --debug-image
# No -o: writes invoice.pdf and invoice_debug.png next to the input
scanlayer invoice.jpg --debug-image
# Validate a batch (files exist, Tesseract reachable, output writable)
# without running OCR or writing anything
scanlayer *.jpg -o ./converted/ --dry-runAll options
| Option | Description |
|---|---|
input | One or more source paths: images (jpg, png, tiff, bmp, gif, webp, jp2) or native .pdf. Glob patterns are expanded. Multiple inputs + a folder -o means batch mode. |
-o, --output | Optional. Output path (single input), or a folder (batch mode). If omitted, each output is written next to its own input, same stem, extension from --format, which also lets --debug-image be used on its own without naming an output file. Must be a file path, not a folder, when --merge is used, and is required in that case: a merge combines multiple inputs into one file, so there is no single input to derive a name from. |
--format | pdf (default), txt, json, tsv, or hocr. See Output Formats. |
--debug-image | Also save <output-stem>_debug.png, whatever --format is. See Debug Visualization. |
--lang | Tesseract language(s), e.g. fra, eng, fra+eng. Default: fra+eng. |
--dpi | DPI to use only if it can't be detected from the image itself. |
--jpeg-quality | JPEG quality for the PDF background image (default 82), used when the background isn't encoded as PNG. |
--whitelist | Characters Tesseract is allowed to recognize, e.g. digits only for a numeric field. |
--blacklist | Characters Tesseract should ignore. |
--min-confidence | Integer 0–100. Words below this confidence are dropped. Default 35. |
--psm | Force a single Tesseract page segmentation mode (0–13, excluding 0 and 2, which are rejected: they only run orientation/script detection and produce no OCR text). Skips the normal multi-PSM race entirely. |
--orientation | Omit for automatic (EXIF + OSD + deskew). none disables all correction. A number is an exact clockwise angle in degrees, skipping auto-detection. See examples. |
--title, --author, --subject | PDF metadata fields. |
--font | Path to a TTF font to embed in the invisible text layer, overriding automatic selection. Useful for scripts the built-in selection doesn't cover (Arabic, Hebrew, Thai, Devanagari…). |
--config | Path to a .yaml/.yml/.json profile applied via configure() before any other flag is processed (later CLI flags still override it). See Configuration. |
--no-column-detection | Disable multi-column reading-order reconstruction for this run only. |
--merge | Combine all inputs into one multi-page output PDF instead of one file per input. Only supported with --format pdf. See Multi-Page and Merge. |
--dry-run | Check that every input file exists and is readable, that Tesseract is reachable, and that output paths are writable, then exit, without running OCR or writing any output. Same exit codes as a normal run. With --merge, validation fails fast on the first bad page (matching convert_merge(), which produces one combined output and never returns exit code 5). |
-v, --verbose | DEBUG-level logging. |
-q, --quiet | Only log errors. Mutually exclusive with --verbose. |
--force | Build output even if the source looks blank/near-uniform (background-only PDF, or an empty result for other formats), instead of raising an error. |
Exit codes
The CLI's exit code is a flattened view of the library's exception hierarchy: see Library API → Exceptions for the exact classes each one corresponds to.
| Code | Meaning | Typical cause |
|---|---|---|
| 0 | Success | n/a |
| 1 | User error | File not found, invalid --format, blank page without --force |
| 2 | Environment error | Tesseract missing/misconfigured, poppler missing for PDF input |
| 3 | Unexpected error | A bug: rerun with --verbose for the full traceback |
| 4 | Processing error | OCR or PDF stage failed operationally (e.g. a timeout), after every precondition already passed |
| 5 | Partial batch failure | Multiple inputs given, at least one failed, the rest still ran |
Debugging exit code 3
An unexpected error (a bug, not a documented failure mode) always prints the exception type and message; add
--verbose to also get the full Python traceback in the log output.
Running from a checkout
If you installed with Option B in Installation
(no pip install scanlayer), there is no scanlayer command on PATH.
Every example on this page and in Examples still works, just
substitute python -m scanlayer for scanlayer:
bash
python -m scanlayer invoice.jpg -o invoice.pdf --lang fra --dpi 300