ocrmypdf
OCRmyPDF core skill — add searchable OCR text layer to scanned PDFs, convert images to searchable PDFs, support 100+ languages via Tesseract. Use when the user needs to OCR a PDF, make a scanned PDF searchable, or extract text from scanned documents.
- Installs
- 48
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/full-stack-skills/ocrmypdf-skills --skill ocrmypdf- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads ocrmypdf automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
OCRmyPDF — Core OCR Guide
Overview
OCRmyPDF adds an OCR text layer to scanned PDF files, allowing them to be searched or copy-pasted. It uses Tesseract OCR, supports 100+ languages, produces PDF/A by default, and distributes work across all CPU cores.
For image processing (deskew, rotate, clean), see the ocrmypdf-image skill. For optimization and PDF/A options, see ocrmypdf-optimize. For batch/Docker/scripting, see ocrmypdf-batch. For Python API and plugins, see ocrmypdf-api.
Installation
One-liner installs (recommended)
| OS | Command |
|---|---|
| Debian / Ubuntu | apt install ocrmypdf |
| Fedora | dnf install ocrmypdf tesseract-osd |
| macOS (Homebrew) | brew install ocrmypdf |
| macOS (MacPorts) | port install ocrmypdf |
| FreeBSD | pkg install py-ocrmypdf |
| Snap | snap install ocrmypdf |
pip install (latest version)
# After installing system dependencies (Tesseract, Ghostscript)
pip install ocrmypdf
Verify
ocrmypdf --version
ocrmypdf --help
Requirements
- Python 3.11+
- Tesseract 4.1.1+ (OCR engine)
- Ghostscript 9.54+ or pypdfium2 (PDF rasterization)
- Optional: jbig2enc (compression), pngquant (image optimization), unpaper (cleaning)
Quick Start
# Basic OCR — input scanned PDF, output searchable PDF/A
ocrmypdf input.pdf output.pdf
# OCR an image file directly
ocrmypdf --image-dpi 300 scan.png output.pdf
# OCR in place (only overwrites on success)
ocrmypdf myfile.pdf myfile.pdf
Language Support
OCRmyPDF uses Tesseract language packs. Install them for your OS:
# Debian / Ubuntu
apt-cache search tesseract-ocr # List all language packs
apt install tesseract-ocr-chi-sim # Chinese Simplified
apt install tesseract-ocr-fra # French
# macOS (Homebrew)
brew install tesseract-lang # All languages
# Fedora
dnf search tesseract-langpack
dnf install tesseract-langpack-ita # Italian
Using languages
# Single language
ocrmypdf -l fra document.pdf output.pdf
# Multiple languages
ocrmypdf -l eng+fra bilingual.pdf output.pdf
# Chinese Simplified + English
ocrmypdf -l chi_sim+eng chinese-doc.pdf output.pdf
Note: Use ISO 639-3 codes for language identifiers.
OCR Modes
Default mode (skip existing text)
# Skip pages that already have text — only OCR pages without text
ocrmypdf input.pdf output.pdf
Force OCR (--force-ocr or -m force)
# Rasterize and OCR all pages, even those with existing text
ocrmypdf --force-ocr input.pdf output.pdf
# v17+ short form:
ocrmypdf -m force input.pdf output.pdf
Redo OCR (--redo-ocr or -m redo)
# Replace existing OCR without rasterizing (preserves quality)
ocrmypdf --redo-ocr input.pdf output.pdf
# v17+ short form:
ocrmypdf -m redo input.pdf output.pdf
Skip text (--skip-text or -m skip)
# Skip pages with any text, only OCR blank/image pages
ocrmypdf --skip-text input.pdf output.pdf
# v17+ short form:
ocrmypdf -m skip input.pdf output.pdf
No OCR (image processing only)
# Apply image processing / PDF/A conversion without OCR
ocrmypdf --ocr-engine none input.pdf output.pdf
Page Selection
# OCR only specific pages
ocrmypdf --pages 1,3,5-10 input.pdf output.pdf
# OCR only the first page, minimal changes elsewhere
ocrmypdf --pages 1 --output-type pdf --optimize 0 input.pdf output.pdf
Output Types
# PDF/A (default) — for archival
ocrmypdf --output-type pdfa input.pdf output.pdf
# Standard PDF
ocrmypdf --output-type pdf input.pdf output.pdf
# Auto (v17+) — speculative PDF/A, falls back to standard PDF
ocrmypdf --output-type auto input.pdf output.pdf
# No output PDF — only produce sidecar text
ocrmypdf --output-type none --sidecar text.txt input.pdf -
Sidecar Text File
# Produce a companion text file with OCR text
ocrmypdf --sidecar output.txt input.pdf output.pdf
Metadata
# Set output PDF metadata
ocrmypdf --title "My Document" --author "Author Name" --subject "Subject" input.pdf output.pdf
Parallel Processing
# Use 4 CPU cores (default: all available)
ocrmypdf --jobs 4 input.pdf output.pdf
# Single-threaded
ocrmypdf --jobs 1 input.pdf output.pdf
Common Recipes
Make a scanned PDF searchable
ocrmypdf scanned.pdf searchable.pdf
Convert image to searchable PDF
ocrmypdf --image-dpi 300 scan.jpg output.pdf
OCR a multilingual document
ocrmypdf -l eng+deu+fra multilingual.pdf output.pdf
Re-OCR with newer Tesseract
ocrmypdf --redo-ocr old-ocr.pdf updated.pdf
Strip all text/OCR from a PDF
ocrmypdf --ocr-engine none --force-ocr input.pdf stripped.pdf
Quick Reference
| Task | Command |
|---|---|
| Basic OCR | ocrmypdf input.pdf output.pdf |
| Specify language | ocrmypdf -l fra input.pdf output.pdf |
| Multiple languages | ocrmypdf -l eng+fra input.pdf output.pdf |
| Force re-OCR all pages | ocrmypdf --force-ocr input.pdf output.pdf |
| Replace existing OCR | ocrmypdf --redo-ocr input.pdf output.pdf |
| Skip pages with text | ocrmypdf --skip-text input.pdf output.pdf |
| Specific pages only | ocrmypdf --pages 1,3,5-10 input.pdf output.pdf |
| Output standard PDF | ocrmypdf --output-type pdf input.pdf output.pdf |
| Extract text sidecar | ocrmypdf --sidecar text.txt input.pdf output.pdf |
| Image to PDF | ocrmypdf --image-dpi 300 image.png output.pdf |
| In-place OCR | ocrmypdf myfile.pdf myfile.pdf |
| Set metadata | ocrmypdf --title "Title" input.pdf output.pdf |
| Parallel jobs | ocrmypdf --jobs 4 input.pdf output.pdf |
Troubleshooting
- "Tesseract not found": Install Tesseract and ensure it's on PATH.
- Poor OCR quality: Check language packs (
-l), try--deskew(see ocrmypdf-image), or--oversample 300. - "Input file has text": Use
--force-ocr,--redo-ocr, or--skip-textas appropriate. - Large output files: See ocrmypdf-optimize for
--optimizelevels and JBIG2. - Signed PDFs: Use
--invalidate-digital-signaturesto override (signatures will be invalidated).
References
FAQ
What does the ocrmypdf skill do?
OCRmyPDF core skill — add searchable OCR text layer to scanned PDFs, convert images to searchable PDFs, support 100+ languages via Tesseract. Use when the user needs to OCR a PDF, make a scanned PDF searchable, or extract text from scanned documents.
How do I install ocrmypdf?
Run npx skills add https://github.com/full-stack-skills/ocrmypdf-skills --skill ocrmypdf in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/ocrmypdf/ (personal) or .claude/skills/ocrmypdf/ (project).
Which AI agents can use ocrmypdf?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is ocrmypdf safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains ocrmypdf?
It is published by full-stack-skills in full-stack-skills/ocrmypdf-skills. It has 48 recorded installs.
Popular docs & writing skills
grill-with-docs
mattpocock/skills
A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
lark-markdown
open.feishu.cn
飞书 Markdown：查看、创建、上传、编辑和比较飞书中的原生 Markdown 文件。当用户要操作飞书 Markdown 文件，或比较其远端版本及本地草稿时使用。纯本地 Markdown 文件操作不触发本 skill。不负责将 Markdown 导入为飞书在线文档，也不负责文件搜索、权限、评论、移动、删除等云空间管理操作。
writing-beats
mattpocock/skills
Writing, exploit; assemble raw material into a journey of beats, grounding each term before a beat leans on it.
writing-shape
mattpocock/skills
Writing, exploit: shape raw material into an article, paragraph by paragraph.
writing-fragments
mattpocock/skills
Writing, explore: mine raw fragments, no structure yet.
writing-for-agents
mattpocock/skills
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.