PDF Skill

Complete guide for PDF operations using Python libraries and CLI tools.

⚡ Feature Cheat Sheet

One-line lookup for every supported operation — find the right tool instantly.

💡 Run any script with --help to see all available options.

Quick Decision Guide

What do you need?
├── Create a new PDF from scratch     → reportlab  (see references/create.md)
├── Extract text / tables             → pdfplumber  (see references/extract.md)
├── Merge / split / rotate pages      → pypdf or qpdf CLI
├── Reorder pages                     → scripts/reorder_pdf.py
├── Add watermark / encrypt / protect → pypdf
├── Fill out a PDF form               → pdf-lib (JS) or pypdf  (see FORMS.md)
├── Extract images from PDF           → pdfimages CLI or pypdf
├── OCR a scanned PDF                 → pdf2image + pytesseract
├── Compress / reduce file size       → scripts/compress_pdf.py (qpdf + pypdf)
├── View PDF info / metadata          → scripts/pdf_info.py
├── Convert images → PDF              → scripts/images_to_pdf.py (reportlab)
├── Convert PDF → images              → scripts/pdf_to_images.py (pdf2image)
├── Compare / diff two PDFs           → scripts/compare_pdf.py
├── Repair a corrupted PDF            → scripts/repair_pdf.py (qpdf + pypdf)
└── List fonts in a PDF               → scripts/list_fonts.py

Installation

Linux (Ubuntu/Debian)

# Python libraries
pip install pypdf pdfplumber reportlab pdf2image pytesseract Pillow --break-system-packages

# System tools
sudo apt-get install -y poppler-utils tesseract-ocr qpdf

# For Chinese OCR
sudo apt-get install -y tesseract-ocr-chi-sim tesseract-ocr-chi-tra

# Node.js (form filling)
npm install pdf-lib

macOS (Homebrew)

# System tools (required for OCR and CLI operations)
brew install qpdf poppler tesseract

# IMPORTANT: Language packs must be installed separately for non-English OCR
brew install tesseract-lang

# Python libraries
pip install pypdf pdfplumber reportlab pdf2image pytesseract Pillow --break-system-packages

# Node.js (form filling)
npm install pdf-lib

⚠️ macOS 注意: tesseract-lang 必须单独安装，否则中文/日文等非英文 OCR 会失败。安装后运行 tesseract --list-langs 确认可用语言。

Verify Installation

# Check Python libraries
python3 -c "import pypdf, pdfplumber, reportlab, PIL; print('✓ Python libs OK')"

# Check system tools
which qpdf       && echo "✓ qpdf OK"       || echo "✗ qpdf not installed"
which tesseract   && echo "✓ tesseract OK"  || echo "✗ tesseract not installed"
which pdftotext   && echo "✓ poppler OK"    || echo "✗ poppler not installed"

# Check OCR languages
tesseract --list-langs 2>/dev/null | head -5

Core Operations

Read & Extract Text

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    for page in pdf.pages:
        print(page.extract_text())

→ For advanced extraction options, see references/extract.md

Extract Tables → DataFrame

import pdfplumber, pandas as pd

with pdfplumber.open("report.pdf") as pdf:
    for page in pdf.pages:
        for table in page.extract_tables():
            df = pd.DataFrame(table[1:], columns=table[0])
            print(df)

Merge PDFs

from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for path in ["a.pdf", "b.pdf", "c.pdf"]:
    writer.append(PdfReader(path))
with open("merged.pdf", "wb") as f:
    writer.write(f)

Split PDF

from pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")
for i, page in enumerate(reader.pages):
    w = PdfWriter()
    w.add_page(page)
    with open(f"page_{i+1}.pdf", "wb") as f:
        w.write(f)

Rotate Pages

reader = PdfReader("scan.pdf")
writer = PdfWriter()
for page in reader.pages:
    page.rotate(90)   # 90 / 180 / 270
    writer.add_page(page)
with open("rotated.pdf", "wb") as f:
    writer.write(f)

Password Protect

from pypdf import PdfReader, PdfWriter

reader = PdfReader("doc.pdf")
writer = PdfWriter()
for page in reader.pages:
    writer.add_page(page)
writer.encrypt("user_pass", "owner_pass", use_128bit=False)  # AES-256
with open("encrypted.pdf", "wb") as f:
    writer.write(f)

CLI Quick Reference (qpdf)

# Merge
qpdf --empty --pages a.pdf b.pdf -- merged.pdf

# Extract pages 1-5
qpdf input.pdf --pages . 1-5 -- out.pdf

# Rotate all pages 90°
qpdf input.pdf output.pdf --rotate=+90

# Remove password
qpdf --password=secret --decrypt locked.pdf unlocked.pdf

# Linearize (web-optimized)
qpdf --linearize input.pdf output.pdf

Available Scripts

Use these scripts directly — no need to rewrite from scratch:

Run any script with --help to see its options.

Reference Files

Load these when you need deeper guidance:

• references/create.md — Building PDFs from scratch with reportlab (Platypus, Canvas, styles, tables, headers/footers)
• references/extract.md — Advanced text/table/image extraction, coordinate-based cropping, word-level data
• references/security.md — Watermarks, encryption, permissions, digital signatures
• references/ocr.md — OCR pipeline, language packs, image preprocessing, quality tuning
• FORMS.md — Complete guide to PDF form filling (AcroForm + XFA, pdf-lib JS)

Quick Reference Table

Common Pitfalls

• Never use Unicode subscripts/superscripts (₂, ⁰) in reportlab — use \x3Csub> / \x3Csuper> XML tags instead, or they render as black boxes
• pdfplumber, not pypdf, for text extraction — pypdf's extract_text() loses layout; pdfplumber is layout-aware
• Encrypted PDFs: pass password= to PdfReader() and pdfplumber.open()
• pip in sandbox: always add --break-system-packages flag
• qpdf for speed: for large batch jobs, prefer qpdf CLI over Python loops
• macOS OCR 语言包: brew install tesseract 仅含英文；非英文 OCR 需额外执行 brew install tesseract-lang
• macOS 系统依赖: OCR 和 CLI 操作需先安装 brew install qpdf poppler tesseract
• 测试表单填充: 没有可填写 PDF 时，先运行 python scripts/create_test_form.py 生成测试表单
• OCR vs pdfplumber: OCR 只适用于扫描件（图片型 PDF）。对原生文本 PDF 提取内容，应使用 pdfplumber（更快更准）
• 中文表单填充: pypdf 内置字体不支持 CJK 字符，中文值可能显示为方块。需要中文表单填充时，使用 pdf-lib (JS) 方案（见 FORMS.md）
• 旋转页面: 没有独立 rotate 脚本，使用 python scripts/batch_convert.py rotate input.pdf -d 90

⛔ Limitations (Not Suitable For)