Installing OCRmyPDF

The easiest way to install OCRmyPDF is to follow the steps for your operating system/platform. This version may be out of date, however.

These platforms have one-liner installs:

Homebrew (macOS and Linux)

brew install ocrmypdf

Debian, Ubuntu

apt install ocrmypdf

Windows Subsystem for Linux

apt install ocrmypdf

Fedora

dnf install ocrmypdf tesseract-osd

Alpine Linux

apk add ocrmypdf

macOS (MacPorts)

port install ocrmypdf

FreeBSD

pkg install py311-ocrmypdf

More detailed procedures are outlined below. If you want to do a manual install, or install a more recent version than your platform provides, read on.

If your operating system is older than those listed here, we recommend installing OCRmyPDF with Homebrew, or using the Docker image.

Installing on Linux

Debian 12 or newer and Ubuntu 22.04 or newer

OCRmyPDF versions in Debian & Ubuntu
OCRmyPDF latest released version on PyPI

Debian 12 Debian 13 Debian unstable

Ubuntu 22.04 LTS Ubuntu 24.04 LTS Ubuntu 26.04 LTS

Users of Debian or Ubuntu may simply

apt install ocrmypdf

As indicated in the table above, Debian and Ubuntu releases may lag behind the latest version, sometimes by several major versions. If the version available for your platform is out of date, see Installing the latest version on Debian and Ubuntu.

For full details on version availability for your platform, check the Debian Package Tracker or Ubuntu launchpad.net.

Note

The Debian and Ubuntu OCRmyPDF packages do not install the JBIG2 encoder. OCRmyPDF works fine without it but will produce larger output files. On Debian 13 or newer and Ubuntu 24.04 or newer, the encoder is packaged and can be installed with apt install jbig2. On older releases, you can build jbig2enc from source; OCRmyPDF will automatically detect it on the PATH. See Installing the JBIG2 encoder.

Installing the latest version on Debian and Ubuntu

Debian and Ubuntu include an older version of OCRmyPDF - you can install that with apt install ocrmypdf. To install the latest version, we recommend installing the system package first, which brings in Tesseract, Ghostscript and other system dependencies, and then using uv to install the latest OCRmyPDF from PyPI:

# Install system dependencies first
sudo apt-get update
sudo apt-get -y install ocrmypdf

# Install uv, if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the latest OCRmyPDF
uv tool install ocrmypdf

uv installs the ocrmypdf command in ~/.local/bin. Open a new terminal (or run uv tool update-shell) so that it is on your PATH, and then run ocrmypdf --version to confirm that the latest version is used rather than the older system version in /usr/bin.

If your system Python is too old for the latest OCRmyPDF, as on Ubuntu 22.04, uv will download a suitable version of Python automatically.

To upgrade later:

uv tool upgrade ocrmypdf

Tip

Ubuntu 22.04 ships Tesseract 4.1.1, which is the oldest version OCRmyPDF supports. Tesseract 5 gives better results; it is available for Ubuntu LTS releases from the alex-p/tesseract-ocr5 PPA: sudo add-apt-repository ppa:alex-p/tesseract-ocr5. Newer Debian and Ubuntu releases already include Tesseract 5.

Alternatively, use Homebrew on Linux for a full-featured installation (see Installing with Homebrew (macOS and Linux)).

To add JBIG2 encoding, on Debian 13 or newer and Ubuntu 24.04 or newer run sudo apt install jbig2; otherwise see Installing the JBIG2 encoder.

Older Debian and Ubuntu releases

Ubuntu 22.04 LTS and Debian 12 are the oldest releases OCRmyPDF supports. Ubuntu 20.04 and Debian 11 have reached the end of standard support, and their Python, Tesseract and Ghostscript are too old for current OCRmyPDF. Consider upgrading to a supported release.

If you cannot upgrade, the most convenient way to install a recent version of OCRmyPDF is to use Homebrew on Linux:

brew install ocrmypdf

See Installing with Homebrew (macOS and Linux) for more information on using Homebrew on Linux. Alternatively, run OCRmyPDF from the Docker image, which carries its own up-to-date dependencies.

Fedora

OCRmyPDF version
OCRmyPDF latest released version on PyPI

Fedora 43 Fedora 44 Fedora Rawhide

Users of Fedora may simply

dnf install ocrmypdf tesseract-osd

tesseract-osd is not installed automatically, but OCRmyPDF needs it for automatic page rotation (--rotate-pages). Tesseract language packs are named tesseract-langpack-<language>, for example tesseract-langpack-deu.

For full details on version availability, check the Fedora Package Tracker.

If the version available for your platform is out of date, install the system package first to satisfy system dependencies, then use uv to install the latest version:

# Install system dependencies first
sudo dnf install ocrmypdf tesseract-osd

# Install uv, if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the latest OCRmyPDF
uv tool install ocrmypdf

Open a new terminal (or run uv tool update-shell) so that ~/.local/bin is on your PATH, then confirm the version with ocrmypdf --version. To install from source instead, see Installing HEAD revision from sources.

Note

OCRmyPDF for Fedora currently omits the JBIG2 encoder, and Fedora does not package it. All JBIG2 patents expired in 2017. OCRmyPDF works fine without it but will produce larger output files. If you build jbig2enc from source, OCRmyPDF will automatically detect it on the PATH. To add JBIG2 encoding, see Installing the JBIG2 encoder.

RHEL, CentOS Stream, AlmaLinux and Rocky Linux 9 and 10

There is no OCRmyPDF package for Red Hat Enterprise Linux or its derivatives, either in the base repositories or in EPEL. Install the system dependencies from the base (AppStream) repositories:

sudo dnf install ghostscript tesseract tesseract-osd tesseract-langpack-eng

Other Tesseract languages are available as tesseract-langpack-<language>, for example tesseract-langpack-deu.

The optional dependencies unpaper and, on version 9, pngquant are available from EPEL. Once EPEL is enabled:

sudo dnf install unpaper pngquant  # pngquant: version 9 only

Then install uv, if not already installed, and use it to install OCRmyPDF:

# Install uv, if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the latest OCRmyPDF
uv tool install ocrmypdf

RHEL 9’s default Python 3.9 is too old for OCRmyPDF; uv will download a suitable version of Python automatically. Open a new terminal (or run uv tool update-shell) so that ~/.local/bin is on your PATH, then confirm the version with ocrmypdf --version.

To add JBIG2 encoding, see Installing the JBIG2 encoder.

Arch Linux (AUR)

ArchLinux

There is an Arch User Repository (AUR) package for OCRmyPDF. OCRmyPDF is not in the official Arch repositories, but its dependencies, including Tesseract and its language data, are.

Installing AUR packages as root is not allowed, so you must first setup a non-root user and configure sudo. The official Docker image, archlinux:latest, does not have a non-root user configured, so users of that image must follow these guides.

Next you should install the base-devel package group. This includes the standard tooling needed to build packages, such as a compiler and binary tools.

sudo pacman -S --needed base-devel git

Now you are ready to install the OCRmyPDF package.

git clone https://aur.archlinux.org/ocrmypdf.git
cd ocrmypdf
makepkg -sri

At this point you will have a working install of OCRmyPDF, but the Tesseract install won’t include any OCR language data. You can install the tesseract-data packages to add supported languages. For example, for English:

sudo pacman -S tesseract-data-eng

As an alternative to this manual procedure, consider using an AUR helper. Such a tool will automatically fetch, build and install the AUR package, resolve dependencies (including dependencies on AUR packages), and ease the upgrade procedure.

If you have any difficulties with installation, check the repository package page.

Note

The JBIG2 encoder is an optional dependency of the OCRmyPDF AUR package. OCRmyPDF works fine without it but will produce larger output files. The encoder is available from the jbig2enc AUR package and may be installed using the same series of steps as for the OCRmyPDF AUR package. Alternatively, it may be built manually from source following the instructions in Installing the JBIG2 encoder. If jbig2enc is installed, OCRmyPDF will automatically detect it.

Alpine Linux

Alpine Linux

OCRmyPDF is in the Alpine Linux community repository. To install it:

apk add ocrmypdf

If the version available for your Alpine release is out of date, consider the Alpine-based Docker image, jbarlow83/ocrmypdf-alpine.

Gentoo Linux

Gentoo Linux

OCRmyPDF is available from the GURU overlay, which must be enabled first. To install OCRmyPDF on Gentoo Linux, use the following commands:

emerge --ask --noreplace app-eselect/eselect-repository dev-vcs/git
eselect repository enable guru
emaint sync --repo guru
emerge --ask app-text/OCRmyPDF

Other Linux packages

OCRmyPDF is also packaged for other distributions, including NixOS (ocrmypdf), Void Linux (python3-ocrmypdf) and openSUSE Tumbleweed. See the Repology page for a full list.

In general, first install the OCRmyPDF package for your system to satisfy system dependencies, then optionally use the procedure Installing with uv to install a more recent version:

# Install uv, if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the latest OCRmyPDF
uv tool install ocrmypdf

Note

The OCRmyPDF Snap package (snap install ocrmypdf) tracks each OCRmyPDF release on the stable channel. Builds of the development branch are available with snap install ocrmypdf --edge. The snap is strictly confined and can only read and write files in your home folder or on removable media; for other locations, use snap run ocrmypdf - - <input.pdf >output.pdf.

Installing with Homebrew (macOS and Linux)

homebrew

Homebrew provides a full-featured OCRmyPDF installation on both macOS and Linux with all recommended dependencies. This is often the easiest way to get a complete, up-to-date installation.

brew install ocrmypdf

This includes Tesseract, Ghostscript, jbig2enc, pngquant, unpaper and all required dependencies. English language support is included by default. For other languages:

brew install tesseract-lang  # Optional: Install all language packs

To upgrade later:

brew upgrade ocrmypdf

Tip

For Linux users: Homebrew on Linux is an excellent choice when your distribution’s package is outdated, your distribution is too old for current OCRmyPDF, or its package is missing optional dependencies like jbig2enc, pngquant, or unpaper. Homebrew provides a consistent, full-featured installation that works across many Linux distributions.

Install Homebrew on Linux: https://brew.sh

Installing on macOS

Homebrew

See Installing with Homebrew (macOS and Linux) above - the installation is identical on macOS.

MacPorts

Macports Version Information

OCRmyPDF is included in MacPorts:

sudo port install ocrmypdf

Note that while this will install tesseract you will need to install the appropriate tesseract language ports, which are named tesseract-<language>. For example, for German:

sudo port install tesseract-deu

Manual installation on macOS

These instructions are for installing a more current version of OCRmyPDF than is available from Homebrew. Note that Homebrew versions usually track releases fairly closely.

If it’s not already present, install Homebrew.

Update Homebrew and install OCRmyPDF’s dependencies, without OCRmyPDF itself:

brew update
brew install --only-dependencies ocrmypdf

Homebrew’s Tesseract includes English only. If you need other languages you can optionally install them all:

brew install tesseract-lang  # Optional: for all language packs

Install uv, if not already installed, and use it to install OCRmyPDF:

# Install uv, if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the latest OCRmyPDF
uv tool install ocrmypdf

Open a new terminal (or run uv tool update-shell) so that ~/.local/bin is on your PATH. The command line program should now be available:

ocrmypdf --help

To upgrade later, run uv tool upgrade ocrmypdf.

Installing on Windows

Native Windows

Note

Administrator privileges will be required for some of these steps.

You must install the following for Windows:

  • Tesseract 64-bit

  • Ghostscript 64-bit (recommended; required for some PDF/A conversions)

  • uv, which installs OCRmyPDF and, if needed, a suitable Python

Using the winget package manager:

winget install -e --id tesseract-ocr.tesseract
winget install -e --id astral-sh.uv

If you prefer not to use winget for uv, you can install it with its standalone installer instead:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Ghostscript is not available from winget. You will need to install it manually, since it does not support automated installs anymore:

Or alternately, using the Chocolatey package manager, install the following when running in an Administrator command prompt:

choco install tesseract
choco install ghostscript
choco install pngquant  # optional

and then install uv using either of the commands above.

Either set of commands will install the required software. At the moment there is no single command to install OCRmyPDF and all of its dependencies on Windows.

Open a new command prompt or PowerShell window, so that the newly installed programs are on your PATH, and install OCRmyPDF. (This can be performed by a user or Administrator.)

uv tool install ocrmypdf

Open another new window, then confirm that OCRmyPDF is available:

ocrmypdf --version

If the ocrmypdf command is not found, run uv tool update-shell and open a new window. To upgrade later, run uv tool upgrade ocrmypdf.

OCRmyPDF will check the Windows Registry and standard locations in your Program Files for third party software it needs (specifically, Tesseract and Ghostscript). To override the versions OCRmyPDF selects, you can modify the PATH environment variable. Follow these directions to change the PATH.

Warning

32-bit Windows is not supported.

Windows Subsystem for Linux

  1. Install Ubuntu 24.04 or 26.04 LTS for Windows Subsystem for Linux, if not already installed.

  2. Follow the procedure to install the latest OCRmyPDF on Ubuntu.

  3. In the Ubuntu (WSL) terminal, create a symlink so that the latest version is found when OCRmyPDF is run from Windows:

sudo ln -s ~/.local/bin/ocrmypdf /usr/local/bin/ocrmypdf

Then, from the Windows command prompt, confirm that the expected version from PyPI (OCRmyPDF latest released version on PyPI) is installed:

wsl ocrmypdf --version

You can then run OCRmyPDF in the Windows command prompt or Powershell, prefixing wsl, and call it from Windows programs or batch files.

Cygwin64

Warning

Cygwin installation is not tested. uv is not available for Cygwin, and some of OCRmyPDF’s Python dependencies, such as pikepdf, pypdfium2 and uharfbuzz, have no Cygwin binaries and must be compiled from source, which may fail. We recommend using Windows Subsystem for Linux, the Docker image, or native Windows instead.

First install the following prerequisite Cygwin packages using setup-x86_64.exe:

python312 (or later)
python312-devel
python312-pip
python312-lxml
python312-imaging

   (where 312 should match the version of Python you installed)

gcc-g++
ghostscript
libexempi-devel
libffi-devel
pngquant
qpdf
libqpdf-devel
tesseract-ocr
tesseract-ocr-devel

Then open a Cygwin terminal (i.e. mintty), and install OCRmyPDF into a virtual environment:

python3.12 -m venv --system-site-packages ~/ocrmypdf-venv
~/ocrmypdf-venv/bin/python -m pip install ocrmypdf
~/ocrmypdf-venv/bin/ocrmypdf --version

The optional dependency “unpaper” is currently not available under Cygwin. Without it, certain options such as --clean will produce an error message. However, the OCR-to-text-layer functionality is available.

Docker

You can also Install the Docker image on Windows. Ensure that your command prompt can run the docker “hello world” container.

Installing on FreeBSD

FreeBSD 
pkg install py311-ocrmypdf

To install a more recent version, first install the system version with pkg to satisfy system dependencies, then install uv from packages and use it to install OCRmyPDF:

pkg install uv
uv tool install ocrmypdf

Some Python dependencies do not publish binaries for FreeBSD and will be compiled from source, so this may require additional development packages.

Installing the Docker image

For some users, installing the Docker image will be easier than installing all of OCRmyPDF’s dependencies. It is also a good option if your operating system is too old to run current OCRmyPDF.

See Installing the Docker image for more information.

Installing HEAD revision from sources

If you have git and uv installed, you can install from source. uv will alert you if Python dependencies cannot be installed; OCRmyPDF will alert you at runtime if system dependencies are missing.

If you prefer to build everything from source, you will need to build pikepdf from source. First ensure you can build and install pikepdf.

To install the latest development version as a command line tool:

# Install uv, if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

uv tool install git+https://github.com/ocrmypdf/OCRmyPDF.git

Or, to work from a local checkout allowing customization:

git clone -b main https://github.com/ocrmypdf/OCRmyPDF.git
cd OCRmyPDF
uv sync

This creates a virtual environment in .venv and installs OCRmyPDF in editable mode along with its dependencies. Run the program with uv run, or activate the environment:

uv run ocrmypdf --help

# or
source .venv/bin/activate
ocrmypdf --help

Note: when installed this way, ocrmypdf will only be accessible through uv run or when the virtual environment is activated.

If not yet installed, the script will notify you about dependencies that need to be installed. The script requires specific versions of the dependencies. Older version than the ones mentioned in the release notes are likely not to be compatible to OCRmyPDF.

Optional Features

OCRmyPDF provides optional features and development tools. We recommend using uv as your package manager.

Installing User Features

User features are available as optional dependencies (extras). When installing OCRmyPDF as a tool:

uv tool install "ocrmypdf[heic]"                   # HEIF/HEIC image support
uv tool install "ocrmypdf[watcher]"                # File watching service
uv tool install "ocrmypdf[webservice]"             # Streamlit web UI
uv tool install "ocrmypdf[watcher,webservice]"     # Multiple features

Or, from a local source checkout:

uv sync --extra heic           # HEIF/HEIC image support
uv sync --extra watcher        # File watching service
uv sync --extra webservice     # Streamlit web UI
uv sync --extra watcher --extra webservice  # Multiple features

Development Tools

Development tools use dependency groups:

# Testing infrastructure
uv sync --group test

# Documentation building
uv sync --group docs

# Enhanced Streamlit development
uv sync --group streamlit-dev

# All development groups
uv sync --all-groups

Why use uv?

  • Modern, fast Python package manager

  • Required for development (testing, docs)

  • Better dependency resolution

  • Consistent across all platforms

Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh or visit https://docs.astral.sh/uv/

For development

To install all of the development and test requirements:

git clone -b main https://github.com/ocrmypdf/OCRmyPDF.git
cd OCRmyPDF
uv sync --all-groups

To add JBIG2 encoding, see Installing the JBIG2 encoder.

Shell completions

Completions for bash and fish are available in the project’s misc/completion folder. The bash completions are likely zsh compatible but this has not been confirmed. Package maintainers, please install these at the appropriate locations for your system.

To manually install the bash completion, copy misc/completion/ocrmypdf.bash to /etc/bash_completion.d/ocrmypdf (rename the file).

To manually install the fish completion, copy misc/completion/ocrmypdf.fish to ~/.config/fish/completions/ocrmypdf.fish.

Note on 32-bit support

We don’t support any 32-bit system, including 32-bit Python or 32-bit Ghostscript on Windows.