Installation

Basic installation

Note

Tesseract Core needs Python 3.10+, ideally in a virtual environment. To run a Tesseract in its own environment with Tesseract.from_source, you also need uv (or conda, for Tesseracts that declare conda requirements). Docker is only needed to build and run container images.

Install Tesseract Core via pip:

$ pip install tesseract-core

Then, verify the installation:

$ tesseract --version

To use Tesseracts from JAX or PyTorch programs, install Tesseract-JAX or Tesseract-Torch alongside it:

$ pip install tesseract-jax    # or tesseract-torch

Installing Docker (for container images)

Building a container image with tesseract build, and running it with tesseract run, tesseract serve, or Tesseract.from_image, requires a container engine. You can skip this section until you want to share or deploy a Tesseract as an image.

Docker Desktop ships with everything you need, including the Docker Engine CLI, Docker Compose, and Docker Buildx. It is available for Windows, macOS, and Linux (Debian- and Fedora-based distros).

If your system is not supported by Docker Desktop, or you prefer a more minimal setup, install the docker engine CLI together with docker-buildx.

Running Docker without sudo

To use Tesseract without sudo, add your user to the docker group (see Docker post-install docs):

$ sudo usermod -aG docker $USER

Then log out and back in to apply the changes.

Warning

Using sudo tesseract may bypass your virtual environment and shadow the tesseract command with conflicting executables. Instead, add your user to the docker group and omit sudo.

Using alternative container engines

The container engine can be configured with the TESSERACT_DOCKER_EXECUTABLE environment variable. Any engine with a docker-compatible CLI (e.g. podman) is supported.

$ export TESSERACT_DOCKER_EXECUTABLE=podman
$ echo "export TESSERACT_DOCKER_EXECUTABLE=podman" >> ~/.bashrc

Runtime installation

The Tesseract Runtime is what serves a Tesseract’s endpoints. Tesseract.from_source installs it into the Tesseract’s own environment for you, so you only need it in your current environment to call tesseract-runtime directly, for example to check gradients, debug, or deploy without containers (see Deploying without a container engine). To install it:

$ pip install tesseract-core[runtime]

Tip

Some shells treat [ and ] as special characters. If the command above fails, escape them (tesseract-core\[runtime\]) or use quotes ("tesseract-core[runtime]").

Common issues

Windows support

Tesseract is natively supported on Windows. Tesseract.from_source needs only Python and uv, and building container images additionally needs Docker Desktop.

Tip

For GPU-accelerated workloads or maximum performance, consider using the Windows Subsystem for Linux (WSL) instead. WSL provides direct access to Linux-native Docker Engine (avoiding Docker Desktop’s virtualization overhead) and GPU passthrough via NVIDIA Container Toolkit.

Conflicting executables

Other software shares the “Tesseract” name (notably Tesseract OCR). If both are installed, the tesseract command may run the other program. For example, tesseract --version then reports Tesseract OCR instead of the Tesseract Core version:

$ tesseract --version
tesseract 5.5.3
 leptonica-1.87.0
 ...

Other tesseract commands fail with errors like read_params_file: Can't open ... or Error during processing.

We recommend always using a dedicated Python virtual environment. If you use zsh, you may also need to refresh the shell’s executable cache:

$ hash -r

You can also bypass the name entirely and invoke Tesseract through the interpreter you installed it into, which is unambiguous:

$ python -m tesseract_core --version

To confirm which executable tesseract resolves to:

$ which tesseract

Missing user privileges

If you lack permissions to access the Docker daemon, commands like tesseract build will fail:

$ tesseract build examples/helloworld
RuntimeError: Could not reach Docker daemon, check if it is running. See logs for details.

Resolve this by adding your user to the docker group as described in Running Docker without sudo.

Development installation

To install everything needed for development on Tesseract Core itself (editable source, runtime, and test dependencies):

$ git clone git@github.com:pasteurlabs/tesseract-core.git
$ cd tesseract-core
$ pip install -e .[dev]
$ pre-commit install