---

name: tesseract description: >- Tesseract is an open-source OCR engine that reads printed text out of images (PNG, JPEG, TIFF) and writes plain text, searchable PDF, hOCR, TSV or ALTO XML. Use when someone asks to "extract text from an image", "OCR this scan", "make a scanned PDF searchable", "read a receipt or serial number from a photo", "get word bounding boxes and confidence", or names tesseract, pytesseract or tesseract.js. Covers the tesseract command line, language data, page segmentation modes, the pytesseract Python wrapper, OpenCV preprocessing and tesseract.js. license: Apache-2.0 compatibility: "Tesseract 5.x command line on Linux, macOS or Windows (commands run on 5.3.4; latest release 5.5.3). pytesseract 0.3.13 needs Python 3.8+ and the tesseract binary on PATH; tesseract.js 7 needs Node.js 16+ or a browser." metadata: author: terminal-skills version: "1.1.0" category: data-ai tags: - ocr - text-recognition - document-processing - image-to-text - open-source repository: https://github.com/tesseract-ocr/tesseract

Tesseract — Open-Source OCR Engine

Overview

Tesseract is a command-line OCR engine and C/C++ library (libtesseract). Since version 4 it recognizes text line by line with an LSTM neural network, supports more than 100 languages through .traineddata files, and writes plain text, searchable PDF, hOCR, TSV, ALTO and PAGE XML. It reads images only (PNG, JPEG, TIFF and other formats Leptonica opens), not PDF, and it does not clean up bad scans much: most accuracy problems are solved before Tesseract runs, by fixing resolution, skew and contrast, and by choosing the right page segmentation mode.

Wrappers call the same engine: pytesseract shells out to the tesseract binary from Python, and tesseract.js runs a WebAssembly build in Node.js and the browser.

Instructions

Install the engine and language data

sudo apt install tesseract-ocr                       # Debian/Ubuntu: engine + eng + osd
sudo apt install tesseract-ocr-deu tesseract-ocr-fra # one package per language (3-letter code)
brew install tesseract                                # macOS: engine + eng + osd
brew install tesseract-lang                           # macOS: all other languages

tesseract --version
tesseract --list-langs

On Windows use the installer published by UB Mannheim (linked from the Tesseract installation docs) and add its folder to PATH. Distributions ship the tessdata_fast models. The tessdata_best repository has slower, slightly more accurate models; put its .traineddata files in a directory and pass --tessdata-dir:

tesseract --tessdata-dir "$HOME/tessdata_best" --list-langs

--tessdata-dir (or the TESSDATA_PREFIX environment variable) must point at the directory that contains the .traineddata files themselves. Only the tessdata repository carries the legacy engine; with distribution models --oem 0 fails with "Tesseract (legacy) engine requested, but components are not present".

Command line

tesseract invoice.png -                         # text to stdout
tesseract invoice.png invoice                   # writes invoice.txt
tesseract brief.png brief -l deu+eng            # several languages, most likely one first
tesseract invoice.png out/invoice txt pdf tsv   # several formats in one pass
tesseract invoice.png invoice --dpi 300 --psm 6 -c preserve_interword_spaces=1
tesseract pages.txt contract pdf                # pages.txt lists one image per line -> one multi-page PDF

• Syntax is tesseract IMAGE OUTPUTBASE [options] [configfile…]. Options (-l, --psm, --oem, --dpi, -c) come before the output configs txt, pdf, hocr, tsv, alto; page (PAGE XML) exists from 5.4.0.
• Use - or stdout as the output base to print, and stdin as the image to read a pipe.
• The output directory must already exist; Tesseract does not create it.
• pdf produces the page image with an invisible text layer; add -c textonly_pdf=1 for the text layer alone.
• Append quiet to hide messages such as "Estimating resolution as 380"; they appear when the image has no DPI metadata, which --dpi 300 also fixes.
• tesseract --print-parameters lists every -c variable. Useful ones: tessedit_char_whitelist, tessedit_char_blacklist, preserve_interword_spaces, user_defined_dpi, thresholding_method (0 Otsu, 1 adaptive Otsu, 2 Sauvola), load_system_dawg and load_freq_dawg (set both to 0 for codes and part numbers that are not dictionary words).
• OMP_THREAD_LIMIT=1 tesseract … keeps one process on one core; set it when running many files in parallel.

Page segmentation modes

# PSM modes control how Tesseract analyzes page layout
# --psm 0: Orientation and script detection only
# --psm 1: Automatic with OSD
# --psm 3: Fully automatic (default)
# --psm 4: Assume single column
# --psm 6: Assume single uniform block of text
# --psm 7: Treat image as single text line
# --psm 8: Treat image as single word
# --psm 11: Sparse text, no order
# --psm 13: Raw line (no layout analysis)

The default expects a full page. A cropped line or word read with --psm 3 often comes back empty; use 7 or 8, and leave about 10 px of white border around the text. --psm 0 needs osd.traineddata and prints the rotation to apply.

Python with pytesseract

# pip install pytesseract Pillow
import pytesseract
from pytesseract import Output
from PIL import Image

# Simple text extraction
text = pytesseract.image_to_string(Image.open("document.png"))

# Languages and engine options go through lang= and config=
text_multi = pytesseract.image_to_string(Image.open("letter.png"), lang="eng+fra+deu", config="--psm 6")

# Word boxes and confidence (TSV as a dict); container rows have conf -1 and empty text
data = pytesseract.image_to_data(Image.open("invoice.png"), output_type=Output.DICT)
for word, conf, x, y, w, h in zip(data["text"], data["conf"], data["left"], data["top"], data["width"], data["height"]):
    if word.strip() and float(conf) >= 60:
        print(f"{word!r} at ({x},{y},{w},{h}) confidence {conf}")

# Searchable PDF as bytes, and a hard time limit in seconds (raises RuntimeError)
pdf_bytes = pytesseract.image_to_pdf_or_hocr("invoice.png", extension="pdf", timeout=30)

# Whitelist characters for serial numbers
serial = pytesseract.image_to_string("serial.png", config="--psm 7 -c tessedit_char_whitelist=0123456789ABCDEF-")

pytesseract starts one tesseract process per call. A missing language raises pytesseract.TesseractError; a missing binary raises TesseractNotFoundError (set pytesseract.pytesseract.tesseract_cmd to its full path on Windows). Output offers STRING, BYTES, DICT and DATAFRAME (needs pandas). NumPy arrays are accepted and treated as RGB or grayscale, so convert OpenCV BGR images first.

Image preprocessing for better accuracy

# prep.py — pip install opencv-python-headless numpy
import cv2
import numpy as np

def preprocess_for_ocr(image_path: str, upscale: float = 2.0) -> np.ndarray:
    """Grayscale -> upscale -> denoise -> deskew -> binarize a phone photo or low-resolution scan."""
    gray = cv2.imread(image_path, cv2.IMREAD_GRAYSCALE)
    if gray is None:
        raise FileNotFoundError(image_path)
    gray = cv2.resize(gray, None, fx=upscale, fy=upscale, interpolation=cv2.INTER_CUBIC)
    gray = cv2.fastNlMeansDenoising(gray, h=10)

    # Deskew: fit a rotated box around the text pixels (dark text becomes white after inversion)
    ink = cv2.adaptiveThreshold(gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY_INV, 31, 15)
    angle = cv2.minAreaRect(cv2.findNonZero(ink))[-1]
    if angle < -45:      # the angle range differs between OpenCV versions; fold it into (-45, 45]
        angle += 90
    elif angle > 45:
        angle -= 90
    h, w = gray.shape
    matrix = cv2.getRotationMatrix2D((w / 2, h / 2), angle, 1.0)
    gray = cv2.warpAffine(gray, matrix, (w, h), flags=cv2.INTER_CUBIC, borderMode=cv2.BORDER_REPLICATE)

    # Adaptive threshold copes with shadows and uneven lighting; result is black text on white
    return cv2.adaptiveThreshold(gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 31, 15)

Skip steps the input does not need: a clean 300 DPI scan is best passed to Tesseract untouched. To see what Tesseract itself made of the image, add the get.images config and inspect the processed TIFF it writes.

Node.js and the browser with tesseract.js

// npm install tesseract.js   (v7; ESM)
import { createWorker, PSM } from "tesseract.js";

const worker = await createWorker("eng");            // language (and OEM) are set here since v5
await worker.setParameters({ tessedit_pageseg_mode: PSM.SINGLE_BLOCK });
const { data } = await worker.recognize("invoice.png");
console.log(data.text, data.confidence);
await worker.terminate();

Create one worker, call recognize for every image, then terminate. Since v6 only text is returned by default; request the rest with worker.recognize(image, {}, { blocks: true, hocr: true }). The first run downloads the language file and caches eng.traineddata in the working directory under Node.js. tesseract.js does not read PDF files.

Examples

Example 1: Make a scanned contract searchable

User request: "contract-scan.pdf is just page images. Make it searchable and give me the text too."

Tesseract cannot open PDFs, so render the pages first (pdftoppm comes with poppler-utils):

pdftoppm -r 300 -png contract-scan.pdf page          # page-1.png, page-2.png
ls page-*.png > pages.txt
tesseract pages.txt contract-searchable -l eng --dpi 300 pdf txt
pdftotext contract-searchable.pdf - | head -5

Result: Tesseract prints Page 0 : page-1.png and Page 1 : page-2.png, then writes contract-searchable.pdf (2 pages, original images with a selectable text layer) and contract-searchable.txt. pdftotext now returns "SERVICE AGREEMENT …" where the original PDF returned nothing.

Example 2: Read totals from skewed receipt photos and flag doubtful words

User request: "I have phone photos of receipts in receipts/. Pull the total from each and tell me which ones you are unsure about."

# extract_totals.py — uses preprocess_for_ocr from prep.py above
import re
import sys
from pathlib import Path

import pytesseract
from pytesseract import Output

from prep import preprocess_for_ocr

for path in sorted(Path(sys.argv[1]).glob("*.jpg")):
    image = preprocess_for_ocr(str(path))
    data = pytesseract.image_to_data(image, lang="eng", config="--psm 6", output_type=Output.DICT)
    words = [(w, float(c)) for w, c in zip(data["text"], data["conf"]) if w.strip()]
    text = " ".join(w for w, _ in words)
    total = re.search(r"Total\s+EUR\s+(\d+[.,]\d{2})", text)
    shaky = [w for w, c in words if c < 60]
    print(f"{path.name}: total={total.group(1) if total else 'NOT FOUND'} low-confidence={shaky}")

python extract_totals.py receipts

Result:

harbor-2026-09-14.jpg: total=71.40 low-confidence=[]
harbor-2026-09-21.jpg: total=71.40 low-confidence=[]

The same photos, half-resolution and rotated 4–6°, give unreadable fragments when passed to Tesseract without preprocessing.

Guidelines

1. Fix the image before tuning Tesseract — aim for about 300 DPI, dark text on a light background, straight lines and no dark scanner borders; upscale small images and deskew rotated ones.
2. PSM selection — PSM 3 for full pages, 4 for a single column such as a receipt, 6 for one block, 7 for one line, 11 for scattered words. A wrong mode is the usual cause of empty output.
3. Language data — pass every language on the page (-l eng+deu); order matters for speed and results. An "Error opening data file …/deu.traineddata" means the language package is not installed.
4. Whitelist characters — for serial numbers and codes set tessedit_char_whitelist and disable the dictionaries; do not use a whitelist for prose.
5. Confidence filtering — use TSV or image_to_data to get per-word confidence (0–100) and send low-confidence fields to a human instead of trusting them.
6. Tables and layout — Tesseract returns reading-order text, not table structure. preserve_interword_spaces=1 keeps column gaps; cropping cells and reading them one by one works better for real tables.
7. Batch work — give the CLI a text file of image paths, or run several processes with OMP_THREAD_LIMIT=1; with tesseract.js reuse one worker.
8. Trusted models only — install .traineddata files from your package manager or the official tesseract-ocr repositories; 5.5.3 fixed memory-safety bugs in model loading, so keep the engine updated when files come from elsewhere.
9. When not to use Tesseract — handwriting, heavily stylized fonts, dense forms and photos of scenes are outside what it does well; a vision model or a layout-aware OCR service is the better tool there. For PDF-centric workflows see the pdf-ocr skill.