Tesseract OCR Engine User Guide

1. Quick Start

Tesseract is an open-source optical character recognition (OCR) engine that converts images of text into machine-readable strings. It supports over 100 languages out of the box, uses an LSTM neural network for recognition, and produces output in multiple formats including plain text, hOCR, ALTO XML, PAGE XML, TSV, and searchable PDF.

Key features:

• LSTM-based neural network recognition engine (primary) with legacy engine fallback
• 100+ language support via downloadable trained data files
• Multiple output formats: plain text, hOCR, ALTO XML, PAGE XML, TSV, PDF, UNLV, box files
• 14 page segmentation modes for different document layouts
• Multi-page TIFF processing
• C and C++ APIs for programmatic integration
• Unicode (UTF-8) support throughout
• User-defined word lists and pattern matching

Prerequisites: Leptonica image library (installed automatically with most package managers)

Install and run (Ubuntu/Debian):

sudo apt install tesseract-ocr

Recognize text from an image:

tesseract input.png output

Tesseract Open Source OCR Engine v5.5.0 with Leptonica

This creates output.txt containing the recognized text.

Tip

Use stdout as the output base to print recognized text directly to the terminal: tesseract input.png stdout.

What to try next: See Installation for all platforms, Configuration for language setup, and Core Usage for output format options.

2. Installation

System Requirements

Platform Installation

Ubuntu/Debian

sudo apt install tesseract-ocr
sudo apt install tesseract-ocr-eng  # English (usually installed by default)
sudo apt install tesseract-ocr-deu  # German (example additional language)

Fedora/RHEL

sudo dnf install tesseract
sudo dnf install tesseract-langpack-eng

macOS (Homebrew)

brew install tesseract

Windows (Chocolatey)

choco install tesseract

Snap

sudo snap install tesseract
sudo snap connect tesseract:removable-media  # Access /media/* paths

From Source (CMake)

git clone https://github.com/tesseract-ocr/tesseract.git
cd tesseract
mkdir build && cd build
cmake .. -DBUILD_TRAINING_TOOLS=ON
make -j$(nproc)
sudo make install
sudo ldconfig

From Source (Autotools)

git clone https://github.com/tesseract-ocr/tesseract.git
cd tesseract
./autogen.sh
./configure
make -j$(nproc)
sudo make install
sudo ldconfig

Important

When building from source, Leptonica must be installed first. Install libleptonica-dev (Debian/Ubuntu) or leptonica (Homebrew) before running cmake/configure.

Installing Language Data

Tesseract requires trained data files (.traineddata) to recognize text. These files must be placed in the tessdata directory.

# Check where tesseract looks for language data
tesseract --list-langs

List of available languages in "/usr/share/tesseract-ocr/5/tessdata" (3):
eng
osd

Download additional language files from the tessdata repositories and place them in the tessdata directory. Three quality tiers are available:

Warning

Do not mix .traineddata files from different repositories. The tessdata_fast and tessdata_best files are LSTM-only and will not work with the legacy engine (--oem 0). The tessdata repository contains combined models that support all engine modes.

Post-Install Verification

tesseract --version

tesseract 5.5.0
 leptonica-1.84.1
  libgif 5.2.1 : libjpeg 8d (libjpeg-turbo 3.0.1) : libpng 1.6.43 : libtiff 4.6.0 : zlib 1.3.1 : libwebp 1.3.2 : libopenjp2 2.5.0
 Found AVX2
 Found AVX
 Found FMA
 Found SSE4.1

The version output shows the detected SIMD instruction sets used to accelerate LSTM recognition. Higher SIMD levels (AVX2, AVX512) provide faster processing.

Install Troubleshooting

Error: Error opening data file /usr/share/tesseract-ocr/5/tessdata/eng.traineddata

Cause: The trained data file for the requested language is not installed or not in the expected path.

Solution:

1. Install the language data package: sudo apt install tesseract-ocr-eng
2. Or download manually and place in the tessdata directory
3. Or set TESSDATA_PREFIX to point to the directory containing your .traineddata files

Prevention: Always verify language availability with tesseract --list-langs after installation.

Error: Tesseract couldn't load any languages!

Cause: The tessdata directory is empty or the TESSDATA_PREFIX environment variable points to the wrong location.

Solution:

1. Check the tessdata path: tesseract --list-langs
2. Download at least one .traineddata file into that directory
3. Or override with --tessdata-dir /path/to/tessdata

Error: leptonica library not found (building from source)

Cause: Leptonica development headers are not installed.

Solution:

# Debian/Ubuntu
sudo apt install libleptonica-dev

# macOS
brew install leptonica

Error: Error in pixReadFromTiffStream: old style jpeg format is not supported

Cause: The input TIFF file uses old-style JPEG compression not supported by the installed libtiff. This is a known issue (GitHub issue #4475).

Solution:

1. Convert the image to a different format first: convert input.tiff input.png
2. Or recompress the TIFF: tiffcp -c lzw input.tiff output.tiff

3. Configuration

Tessdata Directory

Tesseract searches for language data in this order:

1. Path specified by --tessdata-dir command-line option
2. TESSDATA_PREFIX environment variable
3. Compile-time default (typically /usr/share/tesseract-ocr/5/tessdata on Linux)

export TESSDATA_PREFIX=/path/to/tessdata

Note

For Snap installations, the tessdata path defaults to $SNAP_USER_COMMON. Place .traineddata files in ~/snap/tesseract/common/.

Config Files

Tesseract supports configuration files that set internal parameters. Built-in config files are located in tessdata/configs/ and tessdata/tessconfigs/:

Append config file names after the output base:

tesseract input.png output pdf txt

This produces both output.pdf and output.txt.

User Words and Patterns

Improve recognition accuracy for domain-specific text by supplying custom word lists and patterns:

tesseract input.png output --user-words /path/to/wordlist.txt --user-patterns /path/to/patterns.txt

Word list format: one word per line in UTF-8.

Pattern format: uses Tesseract's pattern syntax where \d matches digits and \w matches word characters. Example for US phone numbers: \d\d\d-\d\d\d-\d\d\d\d.

Tip

Sample word and pattern files ship with the source: tessdata/eng.user-words and tessdata/eng.user-patterns.

Setting Variables with -c

Override any internal parameter at runtime:

tesseract input.png output -c tessedit_char_whitelist=0123456789

Common variables:

List all available parameters:

tesseract --print-parameters

See the Admin Guide for the complete configuration reference.

4. Core Usage

Basic OCR

tesseract imagename outputbase [options...] [configfile...]

Note

Use stdin as imagename and stdout as outputbase for pipe-based workflows: cat image.png | tesseract stdin stdout.

Language Selection

# Single language
tesseract input.png output -l fra

# Multiple languages
tesseract input.png output -l eng+fra+deu

When multiple languages are specified, Tesseract loads all models and determines the best language for each word. Loading more languages increases processing time and may reduce accuracy.

Warning

When using --oem 0 (legacy engine), you must use .traineddata files from the tessdata repository (not tessdata_fast or tessdata_best), as those contain only LSTM models.

Page Segmentation Modes (PSM)

Control how Tesseract analyzes the page layout:

tesseract input.png output --psm 6

Both numeric values and symbolic names are accepted (e.g., --psm auto is equivalent to --psm 3).

Tip

For receipts or forms with scattered text, use --psm 11 (sparse text). For a clean scanned page, --psm 3 (auto) works best.

OCR Engine Modes (OEM)

tesseract input.png output --oem 1

Important

The legacy engine (OEM 0) is disabled in builds compiled with DISABLED_LEGACY_ENGINE. OSD modes (PSM 0, 1, 12) also require the legacy engine.

DPI Override

When an image has no embedded resolution metadata, Tesseract may warn about assuming 70 DPI. Override with:

tesseract input.png output --dpi 300

Output Formats

Tesseract supports multiple output formats, each activated by config files or -c variables:

Plain text (default):

tesseract input.png output
# Creates output.txt

Searchable PDF:

tesseract input.png output pdf
# Creates output.pdf

hOCR (HTML with position data):

tesseract input.png output hocr
# Creates output.hocr

ALTO XML:

tesseract input.png output alto
# Creates output.xml

PAGE XML:

tesseract input.png output -c tessedit_create_page_xml=1
# Creates output.page.xml (no built-in config shortcut)

TSV (tab-separated values with bounding boxes):

tesseract input.png output tsv
# Creates output.tsv

Multiple formats simultaneously:

tesseract input.png output pdf txt hocr
# Creates output.pdf, output.txt, and output.hocr

Note

If no output format is explicitly requested (no config file and no -c tessedit_create_* flag), Tesseract defaults to plain text output.

Log Level Control

tesseract input.png output --loglevel ERROR

Valid levels: ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF.

The Leptonica library message level is controlled separately via the LEPT_MSG_SEVERITY environment variable. When unset, Tesseract disables Leptonica debug/info messages by default.

Information Commands

# Show version and library info
tesseract --version

# List available languages
tesseract --list-langs

# Print all tunable parameters
tesseract --print-parameters

# Print fonts table (legacy engine only)
tesseract --print-fonts-table

# Show page segmentation modes
tesseract --help-psm

# Show OCR engine modes
tesseract --help-oem

5. Common Tasks

OCR a Scanned Document to Text

Goal: Extract text from a clean scanned document.

tesseract scan.tiff output -l eng
cat output.txt

Create a Searchable PDF from a Scanned Book

Goal: Convert scanned pages into a searchable PDF that preserves the original image.

tesseract book.tiff book_searchable pdf

For a text-only PDF (no embedded image, smaller file size):

tesseract book.tiff book_textonly -c textonly_pdf=1 pdf

Process a Multi-Page TIFF

Goal: OCR all pages of a multi-page TIFF in one command.

tesseract multipage.tiff output pdf txt

Tesseract handles multi-page TIFF natively. All pages are processed sequentially into a single output file.

Batch Process Multiple Images

Goal: OCR many image files using a file list.

Create a text file listing image paths (one per line):

/path/to/image1.png
/path/to/image2.jpg
/path/to/image3.tiff

tesseract filelist.txt output pdf

OCR Only Digits

Goal: Restrict recognition to numeric characters only.

tesseract invoice.png output -c tessedit_char_whitelist=0123456789

Or use the built-in digits config:

tesseract invoice.png output digits

OCR a Screenshot or Sparse Text

Goal: Extract text from a UI screenshot with text in various positions.

tesseract screenshot.png output --psm 11

Tip

For screenshots, --psm 11 (sparse text) outperforms the default --psm 3 (auto) because it does not assume a document layout.

OCR a Single Line or Word

Goal: Recognize text from a cropped image containing one line.

# Single line
tesseract line.png output --psm 7

# Single word
tesseract word.png output --psm 8

Detect Script and Orientation

Goal: Determine the writing direction and script of a document.

tesseract input.png output --psm 0

Page number: 0
Orientation in degrees: 0
Rotate: 0
Orientation confidence: 22.43
Script: Latin
Script confidence: 8.72

Important

OSD requires the osd.traineddata file and a build with the legacy engine enabled. LSTM-only builds cannot perform OSD.

OCR with Multiple Languages

Goal: Process a document containing text in more than one language.

tesseract multilingual.png output -l eng+deu+fra

List the primary language first for best results.

Extract Bounding Boxes (TSV Output)

Goal: Get word-level coordinates for post-processing.

tesseract input.png output tsv

The TSV output includes columns: level, page_num, block_num, par_num, line_num, word_num, left, top, width, height, conf, text.

Pipe OCR Through stdin/stdout

Goal: Integrate Tesseract into a shell pipeline.

cat image.png | tesseract stdin stdout -l eng --psm 6

Improve Accuracy with Pre-Processing

Goal: Get better results from poor-quality images.

1. Increase resolution: Scan at 300+ DPI
2. Binarize: Convert to black and white before OCR
3. Deskew: Straighten rotated text
4. Remove noise: Apply despeckling filters

# Example using ImageMagick for pre-processing
convert input.jpg -resize 300% -type Grayscale -threshold 50% preprocessed.tiff
tesseract preprocessed.tiff output

6. Troubleshooting

Error: Tesseract fails to read simple numbers

Cause: The default page segmentation mode assumes a page of text, which may misinterpret small images containing only numbers. Community issue #4285.

Solution:

1. Use an appropriate PSM: --psm 7 (single line) or --psm 8 (single word)
2. Restrict character set: -c tessedit_char_whitelist=0123456789
3. Ensure input DPI is at least 300: --dpi 300

Prevention: Always select the PSM that matches your input image layout.

Error: Image paths enclosed in quotes fail on Windows

Cause: On Windows, "Copy as path" adds surrounding quotes that Tesseract does not strip. Community issue #4515.

Solution: Remove the enclosing quotes from the file path before passing to Tesseract.

Error: Tesseract seemingly stuck

Cause: Very large images or complex layouts can cause long processing times. Community issue #3377.

Solution:

1. Reduce image resolution to 300 DPI
2. Use a more specific PSM to reduce layout analysis work
3. Set a processing timeout via the C API: ProcessPages(filename, retry_config, timeout_ms, renderer)

Prevention: Pre-process large images to reduce dimensions to 300 DPI equivalent.

Error: OCR accuracy regression after RNG revert in 5.5.1

Cause: Changes to random number generation in LSTM processing can cause the LSTM to hallucinate extra characters in some cases. Community issue #4523.

Solution:

1. Try processing with --psm 6 instead of --psm 3
2. Ensure you are using the latest .traineddata files matching your Tesseract version

Error: LSTM models recognize random characters instead of asterisk

Cause: The LSTM model has difficulty recognizing the * character, sometimes substituting random characters. Community issue #4458.

Solution:

1. Use the legacy engine for documents with asterisks: --oem 0
2. Post-process OCR output to correct known substitution patterns

Error: Ghost block detected

Cause: Page segmentation may detect spurious text blocks in images with noise or unusual backgrounds. Community issue #3906.

Solution:

1. Pre-process the image to remove background noise
2. Use --psm 6 or --psm 4 to avoid aggressive block detection
3. Increase image contrast before OCR

Warning

If OCR output contains many ~ characters, these are Tesseract rejection markers indicating low confidence. This usually means the image quality is too poor or the wrong language model is selected.

Diagnostic Decision Tree

1. No output at all? Check that the language data file exists (tesseract --list-langs)
2. Wrong language? Verify -l matches the document language
3. Garbled output? Try a different --psm mode for your layout
4. Very slow? Reduce image resolution to 300 DPI, try --oem 1 (LSTM only)
5. Low confidence? Pre-process the image (binarize, deskew, denoise)

7. FAQ

Q: What image formats does Tesseract support?

Tesseract reads any format supported by Leptonica, which typically includes PNG, JPEG, TIFF (single and multi-page), BMP, GIF, WebP, and JPEG 2000. The exact set depends on the image libraries compiled into Leptonica.

Q: How do I use Tesseract from my application?

Tesseract provides both a C++ API (TessBaseAPI class in tesseract/baseapi.h) and a C API (tesseract/capi.h). Initialize with Init(), set the image with SetImage(), then call GetUTF8Text() or use renderers for structured output. See the Admin Guide for the full API reference.

Q: What is the difference between tessdata, tessdata_fast, and tessdata_best?

tessdata_fast contains small, fast LSTM-only models used by most Linux distributions. tessdata_best contains larger, more accurate LSTM-only models. tessdata contains combined legacy + LSTM models needed for --oem 0 or --oem 2. Do not mix files from different repositories.

Q: Can Tesseract recognize handwritten text?

Tesseract is primarily designed for printed text. While it can be trained on handwritten samples, out-of-the-box accuracy for handwriting is poor. Consider specialized handwriting recognition tools.

Q: How do I train Tesseract for a new font or language?

Tesseract includes training tools (lstmtraining, text2image, combine_tessdata, etc.). The process involves generating training images with text2image, creating box files, and training the LSTM network with lstmtraining. See the Admin Guide for the complete training tool reference.

Q: Does Tesseract support PDF input?

No. Tesseract processes raster images. To OCR a PDF, first convert it to images using a tool like pdftoppm or ghostscript, then pass the images to Tesseract.

Q: How do I set the DPI?

Use --dpi VALUE on the command line, or -c user_defined_dpi=VALUE. For best results, use images scanned at 300 DPI or higher.

Q: Can Tesseract process images from URLs?

If built with libcurl support (shown in --version output), Tesseract can fetch images from URLs directly. Otherwise, download the image first.

Q: What does the confidence value mean?

Confidence ranges from 0 to 100. Values above 80 generally indicate reliable recognition. Access per-word confidence via TSV output (the conf column) or via the API with ResultIterator::Confidence().

Q: Why is Tesseract slow on my machine?

Check tesseract --version for SIMD support. If no AVX2/SSE4.1 is listed, the LSTM engine falls back to scalar math, which is significantly slower. Ensure your build enables SIMD optimizations.