# 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):**

```bash
sudo apt install tesseract-ocr
```

**Recognize text from an image:**

```bash
tesseract input.png output
```

```text
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

| Requirement | Details |
|---|---|
| **OS** | Linux, macOS, Windows, FreeBSD |
| **Library** | Leptonica (required, provides image I/O) |
| **Compiler** | C++17-compatible (GCC 7+, Clang 5+, MSVC 2019+) for building from source |
| **Disk** | ~30 MB for engine + ~15 MB per language data file |

### Platform Installation

=== "Ubuntu/Debian"
    ```bash
    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"
    ```bash
    sudo dnf install tesseract
    sudo dnf install tesseract-langpack-eng
    ```

=== "macOS (Homebrew)"
    ```bash
    brew install tesseract
    ```

=== "Windows (Chocolatey)"
    ```bash
    choco install tesseract
    ```

=== "Snap"
    ```bash
    sudo snap install tesseract
    sudo snap connect tesseract:removable-media  # Access /media/* paths
    ```

=== "From Source (CMake)"
    ```bash
    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)"
    ```bash
    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.

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

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

Download additional language files from the [tessdata repositories](https://github.com/tesseract-ocr/tessdata) and place them in the tessdata directory. Three quality tiers are available:

| Repository | Speed | Accuracy | Use Case |
|---|---|---|---|
| `tessdata_fast` | Fastest | Good | Default for most distributions |
| `tessdata_best` | Slowest | Best | Maximum accuracy needed |
| `tessdata` | Medium | Medium | Legacy + LSTM combined |

> [!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

```bash
tesseract --version
```

```text
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:**
```bash
# 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)

```bash
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/`:

| Config File | Purpose |
|---|---|
| `alto` | Enable ALTO XML output |
| `hocr` | Enable hOCR (HTML) output |
| `pdf` | Enable searchable PDF output |
| `tsv` | Enable TSV output |
| `txt` | Enable plain text output (default) |
| `quiet` | Suppress informational messages |
| `digits` | Restrict recognition to digits only |
| `makebox` | Generate box files for training |
| `lstmbox` | Generate LSTM box files for training |
| `lstm.train` | LSTM training mode |
| `logfile` | Enable logging to file |
| `get.images` | Save intermediate images |

Append config file names after the output base:

```bash
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:

```bash
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:

```bash
tesseract input.png output -c tessedit_char_whitelist=0123456789
```

Common variables:

| Variable | Type | Description |
|---|---|---|
| `tessedit_char_whitelist` | string | Only recognize these characters |
| `tessedit_char_blacklist` | string | Never recognize these characters |
| `user_defined_dpi` | int | Override image DPI |
| `tessedit_pageseg_mode` | int | Page segmentation mode (0-13) |
| `textonly_pdf` | bool | PDF with invisible text only (no image) |
| `hocr_font_info` | bool | Include font info in hOCR/TSV output |
| `tessedit_create_hocr` | bool | Enable hOCR output |
| `tessedit_create_alto` | bool | Enable ALTO output |
| `tessedit_create_page_xml` | bool | Enable PAGE XML output |
| `tessedit_create_tsv` | bool | Enable TSV output |
| `tessedit_create_pdf` | bool | Enable PDF output |
| `tessedit_create_txt` | bool | Enable text output |
| `tessedit_create_lstmbox` | bool | Enable LSTM box output |
| `tessedit_create_boxfile` | bool | Enable box file output |
| `tessedit_create_wordstrbox` | bool | Enable WordStr box output |
| `tessedit_write_unlv` | bool | Enable UNLV output |

List all available parameters:

```bash
tesseract --print-parameters
```

See the Admin Guide for the complete configuration reference.

## 4. Core Usage

### Basic OCR

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

| Argument | Description |
|---|---|
| `imagename` | Input image file, multi-page TIFF, or text file listing images (one per line) |
| `outputbase` | Base name for output files (extension added automatically) or `stdout` |
| `options` | CLI flags like `-l`, `--psm`, `--oem`, `-c`, `--dpi` |
| `configfile` | Config files from `tessdata/configs/` or custom paths |

> [!NOTE]
> Use `stdin` as imagename and `stdout` as outputbase for pipe-based workflows: `cat image.png | tesseract stdin stdout`.

### Language Selection

```bash
# 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:

```bash
tesseract input.png output --psm 6
```

| PSM | Name | Description |
|---|---|---|
| 0 | `osd_only` | Orientation and script detection only |
| 1 | `auto_osd` | Automatic page segmentation with OSD |
| 2 | `auto_only` | Automatic page segmentation, no OSD or OCR (not implemented) |
| 3 | `auto` | Fully automatic page segmentation, no OSD **(default)** |
| 4 | `single_column` | Single column of variable-sized text |
| 5 | `single_block_vert_text` | Single uniform block of vertically aligned text |
| 6 | `single_block` | Single uniform block of text |
| 7 | `single_line` | Treat image as a single text line |
| 8 | `single_word` | Treat image as a single word |
| 9 | `circle_word` | Treat image as a single word in a circle |
| 10 | `single_char` | Treat image as a single character |
| 11 | `sparse_text` | Find as much text as possible in no particular order |
| 12 | `sparse_text_osd` | Sparse text with OSD |
| 13 | `raw_line` | Raw line (bypasses Tesseract-specific hacks) |

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)

```bash
tesseract input.png output --oem 1
```

| OEM | Name | Description |
|---|---|---|
| 0 | `tesseract_only` | Legacy engine only |
| 1 | `lstm_only` | LSTM neural network engine only |
| 2 | `tesseract_lstm_combined` | Legacy + LSTM combined |
| 3 | `default` | Use whatever is available **(default)** |

> [!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:

```bash
tesseract input.png output --dpi 300
```

### Output Formats

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

**Plain text (default):**
```bash
tesseract input.png output
# Creates output.txt
```

**Searchable PDF:**
```bash
tesseract input.png output pdf
# Creates output.pdf
```

**hOCR (HTML with position data):**
```bash
tesseract input.png output hocr
# Creates output.hocr
```

**ALTO XML:**
```bash
tesseract input.png output alto
# Creates output.xml
```

**PAGE XML:**
```bash
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):**
```bash
tesseract input.png output tsv
# Creates output.tsv
```

**Multiple formats simultaneously:**
```bash
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

```bash
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

```bash
# 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.

```bash
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.

```bash
tesseract book.tiff book_searchable pdf
```

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

```bash
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.

```bash
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):

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

```bash
tesseract filelist.txt output pdf
```

### OCR Only Digits

**Goal:** Restrict recognition to numeric characters only.

```bash
tesseract invoice.png output -c tessedit_char_whitelist=0123456789
```

Or use the built-in `digits` config:

```bash
tesseract invoice.png output digits
```

### OCR a Screenshot or Sparse Text

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

```bash
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.

```bash
# 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.

```bash
tesseract input.png output --psm 0
```

```text
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.

```bash
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.

```bash
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.

```bash
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

```bash
# 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.

---

_Generated May 2026 from tesseract-ocr/tesseract at 78a8ac8. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._