tesserocr

Common errors

• TesseractNotFoundError: Failed to find Tesseract command

  cause The Tesseract OCR engine executable is not installed on the system, or its path is not included in the system's PATH environment variable.
  fix Install Tesseract-OCR on your operating system. For example, `sudo apt-get install tesseract-ocr` (Linux) or `brew install tesseract` (macOS).

• Error opening data file /usr/local/share/tessdata/eng.traineddata

  cause Tesseract cannot find the required language data files (`.traineddata`). This often happens if the files are missing, corrupted, or located in a non-standard directory.
  fix Ensure that the Tesseract language data files are installed and correctly placed. On Linux, this might be `sudo apt-get install tesseract-ocr-eng`. Alternatively, specify the `tessdata_dir` argument when initializing `PyTessBaseAPI` (e.g., `PyTessBaseAPI(lang='eng', tessdata_dir='/path/to/tessdata/')`).

• ModuleNotFoundError: No module named 'tesserocr'

  cause The `tesserocr` Python package has not been installed in the current Python environment.
  fix Install the package using pip: `pip install tesserocr`.

Warnings

• breaking Tesseract-OCR is a required system-level dependency and must be installed separately on your operating system (e.g., via `apt-get`, `brew`, `choco`). `tesserocr` is a Python wrapper, not a complete Tesseract distribution.
  Fix: Install Tesseract-OCR on your system. For Debian/Ubuntu: `sudo apt-get install tesseract-ocr tesseract-ocr-eng`. For macOS: `brew install tesseract`. For Windows, use official installers or Chocolatey.
• gotcha Tesseract language data files (`.traineddata`) must be accessible to Tesseract. By default, Tesseract looks in its standard data path, but if you have custom paths or multiple installations, you might need to specify `tessdata_dir` during `PyTessBaseAPI` initialization.
  Fix: Ensure `.traineddata` files (e.g., `eng.traineddata`) are in a directory Tesseract can find, or explicitly pass `tessdata_dir='/path/to/tessdata'` and `lang='eng'` to `PyTessBaseAPI`.
• deprecated Earlier versions (pre-2.6.1) had more relaxed Cython version requirements. Starting with v2.6.1, an upper bound `<3.0.0` was added to Cython to avoid breaking changes introduced in Cython 3.0.
  Fix: If building `tesserocr` from source, ensure your Cython version is `<3.0.0`. Rely on pre-built wheels when possible, as they handle this dependency automatically.
• gotcha While `tesserocr` generally supports multiple Python versions, building from source can be complex due to native Tesseract and Leptonica dependencies. Pre-built wheels are available for common Python versions and platforms, but may not cover all niche environments.
  Fix: Prefer using `pip install tesserocr` which will attempt to download a pre-built wheel. If encountering build errors, check the GitHub releases for supported Python/OS combinations or consult the build instructions for your specific environment.

Install

• pip install tesserocr Install Python wrapper

Imports

• PyTessBaseAPI

  from tesserocr import PyTessBaseAPI

• image_to_text

  from tesserocr import image_to_text

• get_tesseract_version

  from tesserocr import get_tesseract_version

• RIL

  from tesserocr import RIL

  Used for specifying result iterator levels (e.g., character, word, line).

Quickstart

This quickstart demonstrates basic text recognition from an image using `tesserocr.PyTessBaseAPI` for more control and `tesserocr.image_to_text` for simplicity. It includes a base64-encoded image to make the example self-contained and runnable.

import tesserocr
from PIL import Image
from io import BytesIO
import base64

# A simple base64 encoded image containing "Hello World" for a runnable example
# In a real scenario, you'd load an image from file: Image.open("path/to/image.png")
img_data = "iVBORw0KGgoAAAANSUhEUgAAAKMAAABRCAYAAADtL/VCAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAAEnQAABJ0AdFcPaeAAAAABTBMVEX///8AAAD///+xO/FBAAACHklEQVR4Xu2ZzytEQRjHn+3+oBv9B5gC927O4QeYM3Y3B38B3L2ZzR+gE2fPnsR/mD0Y+G9zZmbO+J0P921m3zMzt9O9eA+i+3zP/M78e3/qXWwP+qL1l1gYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGBgYGv80v+gN3m82rF44BAAAAAElFTkSuQmCC"
image_bytes = base64.b64decode(img_data)
image = Image.open(BytesIO(image_bytes))

# Initialize Tesseract API
# You might need to specify lang='eng' or tessdata_dir='path/to/tessdata'
# if Tesseract is not configured globally or language files are not found.
api = tesserocr.PyTessBaseAPI(lang='eng')
api.SetImage(image)
text = api.GetUTF8Text()
confidence = api.MeanTextConf()
api.End()

print(f"Detected Text: {text.strip()}")
print(f"Confidence: {confidence}")

# Shorter convenience function for quick OCR
text_short = tesserocr.image_to_text(image, lang='eng')
print(f"Detected Text (short function): {text_short.strip()}")

# Example of getting Tesseract version
print(f"Tesseract Version: {tesserocr.get_tesseract_version()}")