ocrmypdf/OCRmyPDF · error · MissingDependencyError

Could not find program '{program}' on the PATH

Error message

Could not find program '{program}' on the PATH

What it means

get_version() runs `<program> --version` (or equivalent) and wraps FileNotFoundError as MissingDependencyError: the external executable is not installed or not on PATH.

Source

Thrown at src/ocrmypdf/subprocess/_version.py:52

    # ``ocrmypdf.subprocess.run`` affect this function. Binding ``run`` at
    # module load time would capture the real implementation and bypass the
    # patch.
    from ocrmypdf import subprocess as _sp

    args_prog = [program, version_arg]
    try:
        proc = _sp.run(
            args_prog,
            close_fds=True,
            text=True,
            stdout=PIPE,
            stderr=STDOUT,
            check=True,
            env=env,
        )
        output: str = proc.stdout
    except FileNotFoundError as e:
        raise MissingDependencyError(
            f"Could not find program '{program}' on the PATH"
        ) from e
    except CalledProcessError as e:
        if e.returncode != 0:
            log.exception(e)
            raise MissingDependencyError(
                f"Ran program '{program}' but it exited with an error:\n{e.output}"
            ) from e
        raise MissingDependencyError(
            f"Could not find program '{program}' on the PATH"
        ) from e

    # Some tools (e.g. veraPDF launched on a recent JDK) print warnings before
    # the version line, so scan each line rather than only the start of output.
    version = None
    for line in output.splitlines():
        match = re.match(regex, line.strip())
        if match:

View on GitHub (pinned to 5074a0b0e1)

Solutions

1. Install the missing program (e.g. apt-get install tesseract-ocr) and verify with `tesseract --version` in the same shell/env
2. Ensure the binary's directory is on PATH for the Python process (check os.environ['PATH'])
3. In Docker/CI, add the package to the image rather than relying on the host
4. For plugin tools, verify the program name string is correct

Example fix

# before
ver = get_version('tesseract', regex=r'tesseract (.*)')
# after
import shutil
if not shutil.which('tesseract'):
    raise SystemExit('install tesseract: apt-get install tesseract-ocr')
ver = get_version('tesseract', regex=r'tesseract (.*)')

import shutil\nif not shutil.which(program):\n    raise SystemExit(f'{program} not installed or not on PATH')

try:\n    v = get_version(program, regex=...)\nexcept MissingDependencyError as e:\n    raise RuntimeError(f'install {program}: {e}') from e

When it happens

Trigger: Calling get_version(program, ...) or any code path that checks a tool's version (tesseract, qpdf, ghostscript, unpaper, etc.) when the binary cannot be found via shutil.which/Popen.

Common situations: Missing system dependency in Docker/CI images, venv activation without the tool installed, Windows installs where the tool isn't on PATH, typos in the program name for custom plugins.

Related errors

• Ran program '{program}' but it exited with an error: {e.outp
• The program '{program}' did not report its version. Message
• Ghostscript {gs_version} contains serious regressions and is
• Tesseract 5.4.0 is not supported due to regressions in this

AI-assisted analysis of ocrmypdf/OCRmyPDF@5074a0b0e1 (2026-08-27). Data as JSON: /api/errors/abfcb250248311c1. Report an issue: GitHub.