ocrmypdf/OCRmyPDF · error · MissingDependencyError

Ghostscript 10.0.0 through 10.02.0 (your version: {gs_versio

Error message

Ghostscript 10.0.0 through 10.02.0 (your version: {gs_version}) contain serious regressions that corrupt PDFs with existing text, such as those processed using --skip-text or --redo-ocr (or --mode skip/redo). Please upgrade to a newer version, or use --output-type pdf to avoid Ghostscript, or use --force-ocr (or --mode force) to discard existing text.

What it means

Ghostscript 10.0.0–10.02.0 corrupt PDFs that already contain text when it reprocesses them. If your options use ProcessingMode.skip or redo with those versions, check_options() aborts with MissingDependencyError before damage can occur.

Source

Thrown at src/ocrmypdf/builtin_plugins/ghostscript.py:203

    # Only require Ghostscript for pdfa* output types (not 'auto' or 'pdf')
    # 'auto' mode uses best-effort PDF/A without Ghostscript fallback
    if options.output_type.startswith('pdfa'):
        check_external_program(
            program='gs',
            package='ghostscript',
            version_checker=ghostscript.version,
            need_version='9.54',  # RHEL 9's version; Ubuntu 22.04 has 9.55
        )
        gs_version = ghostscript.version()
        if gs_version in BLACKLISTED_GS_VERSIONS:
            raise MissingDependencyError(
                f"Ghostscript {gs_version} contains serious regressions and is not "
                "supported. Please upgrade to a newer version."
            )
        if Version('10.0.0') <= gs_version < Version('10.02.1') and (
            options.mode in (ProcessingMode.skip, ProcessingMode.redo)
        ):
            raise MissingDependencyError(
                f"Ghostscript 10.0.0 through 10.02.0 (your version: {gs_version}) "
                "contain serious regressions that corrupt PDFs with existing text, "
                "such as those processed using --skip-text or --redo-ocr "
                "(or --mode skip/redo). Please upgrade to a newer version, or use "
                "--output-type pdf to avoid Ghostscript, or use --force-ocr "
                "(or --mode force) to discard existing text."
            )
        if ghostscript.jpeg_truncation_bug(gs_version):
            log.warning(
                "Ghostscript %s contains JPEG encoding errors that may corrupt "
                "images. OCRmyPDF will attempt to mitigate, but this version is "
                "strongly not recommended. Please upgrade to Ghostscript %s or "
                "later, which fixes this.",
                gs_version,
                ghostscript.GS_JPEG_TRUNCATION_FIXED,
            )
        if options.output_type == 'pdfa':
            options.output_type = 'pdfa-2'

View on GitHub (pinned to 5074a0b0e1)

Solutions

  1. Upgrade Ghostscript to 10.02.1 or newer.
  2. Use --output-type pdf to bypass Ghostscript entirely.
  3. Switch to --force-ocr (mode=force) so existing text is discarded and the regression does not apply.

Example fix

# before
ocr(in.pdf, out.pdf, skip_text=True)
# after (one of)
ocr(in.pdf, out.pdf, skip_text=True, output_type='pdf')
ocr(in.pdf, out.pdf, force_ocr=True)
Defensive patterns

Strategy: validation

Validate before calling

from packaging.version import Version
from ocrmypdf.builtin_plugins import ghostscript
v = ghostscript.version()
if Version('10.0.0') <= v < Version('10.02.1'):
    assert options_mode not in ('skip', 'redo') or output_type == 'pdf', \
        'GS 10.0-10.02.0 corrupts skip/redo output unless --output-type pdf'

Prevention

When it happens

Trigger: Running with --skip-text/--redo-ocr (or mode=skip/redo) and Ghostscript >=10.0.0 and <10.02.1 while producing a PDF/A (default output type).

Common situations: New distro ships Ghostscript 10.0/10.1; default output type is pdfa which routes through Ghostscript, colliding with skip/redo mode.

Related errors

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