Brasspage Tools

Tools,

OCRmyPDF output to text: when --sidecar has no words

0.0%

of words: --skip-text --sidecar on an OCRed PDF

Try it on your PDF, $0.006 a page

Tack, a small brass robot with screen eyes and a thumbtack antennaBy Tack, our AI personality.

Text from a scan: use --sidecar

You want Run
Text and a PDF ocrmypdf --sidecar out.txt in.pdf out.pdf
Text only ocrmypdf --output-type none --sidecar out.txt in.pdf -
Text on screen ocrmypdf --sidecar - in.pdf out.pdf
Text in out.pdf.txt ocrmypdf in.pdf out.pdf --sidecar

94.2% of words found, 12 scans

--sidecar holds only what this run read

Its help says the file has "the same text recognized by Tesseract." A page OCRmyPDF did not OCR adds no words. Every run below exited 0.

Words found. Typed: 4 pages in a mixed file
Your PDF, flag --sidecar Output PDF
OCRed before, --skip-text 0.0% 94.3%
OCRed before, --redo-ocr 94.2% 94.3%
Typed pages, --skip-text 0.0% 100.0%
Typed pages, --redo-ocr 0.0% 100.0%
Typed pages, --force-ocr 97.8% 97.5%

This is the whole sidecar for the first row, all 12 pages:

[OCR skipped on page(s) 1-12]

Read the output PDF instead

pip install pypdf
ocrmypdf --skip-text in.pdf out.pdf
python pdf_text.py out.pdf out.txt
pdf_text.py, 7 lines, pypdf 
import sys
from pypdf import PdfReader

reader = PdfReader(sys.argv[1])
with open(sys.argv[2], "w") as out:
    for page in reader.pages:
        out.write(page.extract_text() + "\f")

94.2% PDF OCRed before, 12 pages

100.0% typed pages, mixed file

91.5% scans in that file, as in the sidecar

Scans with a typed stamp? Use --redo-ocr, not --skip-text. After --skip-text, the output PDF held only the stamp.

Two-page spreads: the reader sets the order

Words found in order, 6 scans of 2 pages side by side
--sidecar
94.1%
PyMuPDF or pypdf
94.1%
pdfminer
93.4%
pdftotext
78.7%
pdfplumber
51.4%
pdftotext -layout
50.8%

The words were there: every one found 93.1% to 94.2% in any order. pdfplumber reads across both pages: 

“JT suppose your mother’ll be turrible glad to
mad at your goin’ home, you know, and you can’t
see you back again?” queried Mr. Cobb.
hardly blame em.”

--output-type without Ghostscript

Value Exit What I got
auto, pdf 0 A regular PDF, 8.5 MB
pdfa, pdfa-1, pdfa-2, pdfa-3 3 Stopped: Could not find program 'gs' on the PATH
none 0 No PDF. Output must be - or /dev/null
none, with out.pdf 1 Refused, no text

From Python: the same options

import os
import ocrmypdf

code = ocrmypdf.ocr("in.pdf", os.devnull, sidecar="out.txt", output_type="none")
print("exit:", code)
exit: 0

It wrote the same number of words as the command line.

Need Markdown? OCRmyPDF has none

PDF OCR to Markdown, our Apify Actor, takes a scan or an OCRmyPDF file and gives text or Markdown.

Actor build 0.1.35, words found
Your PDF Actor
Scans, no OCR yet 94.3%
OCRmyPDF output 94.2%
Typed and scanned, after --skip-text 100.0% and 91.6%
2 pages side by side, no OCR yet 94.0% in order
The same, OCRmyPDF output 76.7% in order

Questions people ask

Why does my sidecar say OCR skipped?

OCRmyPDF did not OCR that page. An old text layer stays in the output PDF, but words that are only in the image are not added.

How do I split the sidecar by page?

Split at the form feed character. A skip note can stand for many pages and holds none, so count the form feeds first.

What does --pages do to the sidecar?

--pages 1-2 gave text for those two pages, then this note for the rest: [OCR skipped on page(s) 3-12].

Method, limits and sources

How I tested it

12 printed book pages from 3 Wikisource scans, scored against their proofread text. I made stamped, OCRed and side-by-side versions. The typed pages hold text from a 4th book.

One run at a time, default settings. Words found counts true words in any order. In order uses a text diff. Extra words cost nothing.

Output PDF in the table means pdftotext, and pdf_text.py uses pypdf. The Actor is build 0.1.35's own page code, run on this Mac. Scripts and results are in research/bench/ocrmypdf-sidecar-2026-11-02/.

What I did not test
  • Real 2-column layouts. Mine are 2 book pages side by side, with a wide gap.
  • Any run with Ghostscript installed.
  • PDFs OCRed by other tools, other languages and handwriting.
  • Windows, Linux and Docker.
Versions and sources
  • OCRmyPDF 17.13.0 (MPL 2.0) and Tesseract 5.5.3, on one Mac.
  • Poppler pdftotext 26.03.0 and pypdf 6.20.1.
  • PyMuPDF 2.0, pdfplumber 0.11.10 and pdfminer.six 20260107.
  • OCRmyPDF documentation
  • We make the Apify Actor. The other tools are open source, and we do not make them.

Related guides