tesserocr Documentation

To install tesserocr on Linux or BSD/MacOS, you must first ensure the system dependencies libtesseract (>=3.04) and libleptonica (>=1.71) are installed. On Debian/Ubuntu, use:

$ apt-get install tesseract-ocr libtesseract-dev libleptonica-dev pkg-config

Once dependencies are installed, you can install the Python package via pip:

$ pip install tesserocr

If the setup script cannot detect your include/library directories, you can override them using CPPFLAGS:

$ CPPFLAGS=-I/usr/local/include pip install tesserocr

After building Tesseract, you must download the trained data files and set the TESSDATA_PREFIX environment variable.

cd F:\Project
git clone --depth 1 https://github.com/tesseract-ocr/tessconfigs tessdata
curl -L https://github.com/tesseract-ocr/tessdata/raw/4.1.0/eng.traineddata --output F:\Project\tessdata\eng.traineddata
curl -L https://github.com/tesseract-ocr/tessdata/raw/4.1.0/osd.traineddata --output F:\Project\tessdata\osd.traineddata
SET TESSDATA_PREFIX=F:\Project\tessdata

To build tesserocr on Windows, you must first manually build and install its dependencies: zlib, libpng, leptonica, and tesseract.

Prerequisites

• cmake
• Visual Studio Community
• unzip (via Git for Windows)
• git for windows (optional)
• curl (optional)

1. Initialize Project Structure

Set up a destination directory for dependencies and initialize the Visual Studio x64 environment.

mkdir F:\win64
set INSTALL_DIR=F:\win64
set PATH=%PATH%;%INSTALL_DIR%\bin

mkdir F:\Project & cd Project

call "c:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat" x64

Note: Replace F: with your preferred drive (e.g., C:).

Once the dependencies and Tesseract are installed, you can build the Python bindings.

1. Clone the repository:

git clone https://github.com/sirfz/tesserocr.git
cd tesserocr

2. Build and install using setup.py:

SET VS90COMNTOOLS=%VS140COMNTOOLS%
SET INCLUDE=%INCLUDE%;%INSTALL_DIR%\include
SET LIBPATH=%LIBPATH%;%INSTALL_DIR%\lib

pip install -r requirements-dev.txt
python setup.py clean --all
python setup.py build
python setup.py bdist_wheel
pip uninstall tesserocr
pip install dist\tesserocr-2.5.2b0-cp38-cp38-win_amd64.whl

3. Post-installation: Copy the required DLLs to your Python site-packages directory (adjust path to your Python version):

copy F:\win64\bin\*.dll "C:\Program Files\Python38\Lib\site-packages\"

For Windows, the recommended method is using Conda, which provides stand-alone packages containing all necessary Windows libraries (no separate Tesseract installation required).

Using the simonflueckiger channel:

> conda install -c simonflueckiger tesserocr

Using the conda-forge channel:

> conda install -c conda-forge tesserocr

Alternatively, you can download pre-built wheel files from the simonflueckiger/tesserocr-windows_build/releases repository and install them via pip:

> pip install <package_name>.whl

If tesserocr cannot automatically detect your tessdata path (which contains .traineddata files), you can specify it in two ways:

1. Set the TESSDATA_PREFIX environment variable.
2. Pass the path argument when initializing PyTessBaseAPI.

You can verify available languages and the current tessdata path using get_languages().

To ensure tesserocr is working correctly, run the following Python script. This checks the version, available languages, and performs a basic OCR task using a PIL image.

import tesserocr
print(tesserocr.PyTessBaseAPI.Version())
print(tesserocr.get_languages())

from PIL import Image
image = Image.open(r'F:	est_image.png')
with tesserocr.PyTessBaseAPI() as api:
    api.SetImage(image)
    print(api.GetUTF8Text())

import tesserocr
print(tesserocr.PyTessBaseAPI.Version())
print(tesserocr.get_languages())

from PIL import Image
image = Image.open(r'F:\Project\tesserocr\tests\eurotext.png')
with tesserocr.PyTessBaseAPI() as api:
    api.SetImage(image)
    print(api.GetUTF8Text())

For simple tasks, tesserocr provides high-level helper functions that work directly with Pillow (PIL) images or file paths. These functions are thread-safe and can be used with Python's threading module for efficient concurrent processing.

import tesserocr
from PIL import Image

# Check version and available languages
print(tesserocr.tesseract_version())
print(tesserocr.get_languages())

# OCR from a PIL Image object
image = Image.open('sample.jpg')
print(tesserocr.image_to_text(image))

# OCR from a file path
print(tesserocr.file_to_text('sample.jpg'))

The PyTessBaseAPI class provides direct access to the Tesseract C++ API. It is highly recommended to use it as a context manager (via a with statement) to ensure the API is automatically finalized. If not using a context manager, you must call api.End() explicitly.

Example of reusing an API instance for multiple images:

from tesserocr import PyTessBaseAPI

images = ['sample.jpg', 'sample2.jpg', 'sample3.jpg']

with PyTessBaseAPI() as api:
    for img in images:
        api.SetImageFile(img)
        print(api.GetUTF8Text())
        print(api.AllWordConfidences())