OCRmyPDF Files

Changes

• OCRmyPDF now requires pikepdf 10.2 or later, up from pikepdf 10. This is the first release that provides pikepdf.NamePath, the Object.as_int() family of type-safe accessors, and a thread-local explicit_conversion(). OCRmyPDF uses all three to read optional values out of PDFs it did not write.
• HEIF/HEIC input support is now an opt-in extra, ocrmypdf[heic], instead of a default dependency. The pi-heif package we previously depended on is discontinued; its successor pillow-heif bundles libheif, libde265 and x265 in its wheels, making the wheel as a whole GPLv2-licensed, so we do not install it by default. Install ocrmypdf[heic] if you feed HEIC images to OCRmyPDF. The Docker image and snap do not include it. {issue}1746
• A Tagged PDF that is refused because it appears to contain real text now exits with code 6 (already_done_ocr) instead of code 2 (input_file), matching the exit code for a PDF with prior OCR. Scripts that check for exit code 2 on tagged PDFs need updating. Thanks @BetterAndBetterII. {issue}1551
• The snap package is now built and published from our CI rather than Launchpad, so the stable channel tracks releases again instead of being frozen at v16.4.2. It is based on core26 and includes a JBIG2 encoder.

Fixes

• Text copied or searched in a --output-type pdfa file came out as garbage (a stable substitution of unrelated characters, or nothing at all) when the PDF/A conversion ran through Ghostscript 9.56 through 10.04.x, which includes the Ghostscript in Ubuntu 24.04. fpdf2 writes each font's ToUnicode CMap as a single bfchar block, but the CMap specification allows at most 100 entries per block, and those Ghostscript releases discard the whole map when a block is larger. Any page with more than 100 distinct glyphs was affected, which is nearly every page of prose. CFF CID-keyed fonts such as Noto Sans CJK have the same problem in their Encoding CMap, where those Ghostscript releases then also draw the wrong glyphs. OCRmyPDF now splits every CMap block to 100 entries as fpdf2 writes it, for every fpdf2 release. fpdf2 2.8.9 will split the ToUnicode blocks itself but not the Encoding blocks, so the fix stays in place. Thanks @olafure for the analysis ({issue}1747, fpdf2 issue py-pdf/fpdf2#1952).
• Words containing fi, ff, fl and similar pairs extracted with the letters missing (con dentiality, e ects) from --output-type pdfa files when the PDF/A conversion ran through Ghostscript 10.05.0 through 10.06.x. Those Ghostscript releases drop ToUnicode entries that expand to more than one character (Ghostscript bug 709030, fixed in 10.07.0), and the fpdf2 renderer's HarfBuzz shaping had been forming optional Latin ligatures whose entries do exactly that. Invisible text in scripts that do not need shaping is now encoded one glyph per character, so no such entries exist to lose. Complex scripts still get shaped, and OCRmyPDF now warns when an affected Ghostscript is in use, since their conjunct mappings can still be dropped. Thanks @kmn5 ({issue}1744).
• A malformed PDF that stores something other than a dictionary at a structural key -- /Resources, /Resources /XObject, /Root /AcroForm, /Root /MarkInfo, /Root /Names, /Root /PieceInfo, an annotation's /A, or an image's /SMask -- is now tolerated everywhere rather than in the handful of places that had been hardened individually. Such a file is read as though the key were absent, which is what the well-guarded paths already did.
• An image XObject with no /Subtype no longer raises out of the optimizer.
• PdfInfo no longer aborts on a /MarkInfo << /Marked 1 >>, where a producer wrote a flag as an integer instead of a Boolean. Thanks @linhongyu510 ({issue}1742).
• A page /UserUnit written as a PDF Real is now read exactly rather than via binary floating point, so the digits the file wrote are the digits used.
• --sidecar now refuses any spelling of the input or output file, not just a byte-identical one. ocrmypdf in.pdf out.pdf --sidecar ./in.pdf was accepted and then silently overwrote the input PDF with the OCR text. Paths are now compared after resolving ., .., symlinks and filesystem case. Thanks @linhongyu510.
• --deskew and --rotate-pages now warn that they will have no effect when combined with --ocr-engine none, since skew and orientation are measured by the OCR engine. Other image processing options are unaffected. Thanks @Anai-Guo. {issue}1735
• Installation documentation refreshed for current platforms: Ubuntu 26.04 and Fedora 43/44 added, Ubuntu 20.04 dropped, and uv tool install shown in place of pip.
• Documentation: corrected the list of platforms that ship a JBIG2 encoder, which now includes Debian and Ubuntu. Thanks @lcorbasson.
• Release process and CI improvements.