PDF Edit — General PDF Processing with PyMuPDF

Use PyMuPDF (fitz) for all PDF operations. It handles both editing and content extraction in a single library.

Prerequisites

PyMuPDF loads automatically via uv run --with pymupdf:

uv run --with pymupdf python -c "import fitz; print(fitz.version)"

Common Operations

All snippets assume import fitz and use raw strings (r"...") for Windows paths.

1. Merge PDFs

uv run --with pymupdf python -c "
import fitz
dst = fitz.open()
for path in [r'dir\file1.pdf', r'dir\file2.pdf']:
    src = fitz.open(path)
    dst.insert_pdf(src)
    src.close()
dst.save(r'dir\output.pdf', garbage=4, deflate=True)
dst.close()
print('Merged')
"

2. Split PDF (extract specific pages)

uv run --with pymupdf python -c "
import fitz
src = fitz.open(r'dir\input.pdf')
dst = fitz.open()
dst.insert_pdf(src, from_page=0, to_page=0)  # first page only
dst.save(r'dir\page1.pdf')
dst.close()
src.close()
print('Split')
"

3. Extract text

uv run --with pymupdf python -c "
import fitz
doc = fitz.open(r'dir\input.pdf')
for i, page in enumerate(doc):
    text = page.get_text('text')  # 'text', 'blocks', 'html', 'dict', 'json'
    print(f'--- Page {i+1} ---')
    print(text)
doc.close()
"

4. Extract images

uv run --with pymupdf python -c "
import fitz, os
doc = fitz.open(r'dir\input.pdf')
for i, page in enumerate(doc):
    for j, img in enumerate(page.get_images()):
        xref = img[0]
        pix = fitz.Pixmap(doc, xref)
        if pix.n - pix.alpha < 4:
            pix.save(rf'dir\page{i+1}_img{j+1}.png')
        else:
            pix1 = fitz.Pixmap(fitz.csRGB, pix)
            pix1.save(rf'dir\page{i+1}_img{j+1}.png')
        print(f'Page {i+1}, image {j+1}: saved')
doc.close()
"

5. Rotate pages

uv run --with pymupdf python -c "
import fitz
doc = fitz.open(r'dir\input.pdf')
for page in doc:
    page.set_rotation(90)  # 0, 90, 180, 270
doc.save(r'dir\rotated.pdf', garbage=4, deflate=True)
doc.close()
print('Rotated')
"

6. Encrypt / password-protect

uv run --with pymupdf python -c "
import fitz
doc = fitz.open(r'dir\input.pdf')
doc.save(r'dir\encrypted.pdf',
    encryption=fitz.PDF_ENCRYPT_AES_256,
    user_pw='user123',
    owner_pw='owner456')
doc.close()
print('Encrypted')
"

7. Decrypt / open encrypted PDF

uv run --with pymupdf python -c "
import fitz
doc = fitz.open(r'dir\encrypted.pdf')
if doc.is_encrypted:
    doc.authenticate('user123')
    print('Pages:', doc.page_count)
doc.close()
"

8. Page to image (PNG/JPEG)

uv run --with pymupdf python -c "
import fitz
doc = fitz.open(r'dir\input.pdf')
page = doc[0]
pix = page.get_pixmap(dpi=150)  # default 72
pix.save(r'dir\page1.png')
doc.close()
print('Saved as image')
"

9. Compress / optimize

uv run --with pymupdf python -c "
import fitz
doc = fitz.open(r'dir\input.pdf')
doc.save(r'dir\optimized.pdf',
    garbage=4,        # remove unused objects
    deflate=True,     # compress streams
    clean=True)       # clean up structure
doc.close()
print('Optimized')
"

10. Add text annotation / watermark

uv run --with pymupdf python -c "
import fitz
doc = fitz.open(r'dir\input.pdf')
for page in doc:
    r = page.rect
    page.insert_text(
        (r.width/2 - 50, r.height/2),
        'WATERMARK',
        fontsize=48,
        color=(0.5, 0.5, 0.5),
        overlay=False)
doc.save(r'dir\watermarked.pdf')
doc.close()
print('Watermarked')
"

11. Inspect / get metadata

uv run --with pymupdf python -c "
import fitz
doc = fitz.open(r'dir\input.pdf')
print('Pages:', doc.page_count)
print('Metadata:', doc.metadata)
print('Table of Contents:', doc.get_toc())
for page in doc:
    print(f'Page {page.number + 1}: {page.rect.width:.0f}x{page.rect.height:.0f}')
doc.close()
"

12. Delete / reorder pages

uv run --with pymupdf python -c "
import fitz
doc = fitz.open(r'dir\input.pdf')
# Delete page 2 (0-indexed)
doc.delete_page(1)
# Move page 1 to after page 3
doc.move_page(0, 2)
doc.save(r'dir\reordered.pdf')
doc.close()
print('Reordered')
"

Gotchas

• Windows paths: Always use raw strings (r"C:\path\file.pdf") or escape backslashes ("C:\\path\\file.pdf")
• Turkish/special characters in filenames: handled correctly with raw strings
• Encrypted files: Check doc.is_encrypted before reading; call doc.authenticate(password) to unlock
• Resource cleanup: Always call doc.close() to release file handles, especially in loops
• Merge vs insert_pdf: insert_pdf copies pages from another PDF document object; first open each source with fitz.open()
• Performance: For large PDFs (>100 pages), use save(garbage=4, deflate=True) to keep file size manageable
• pypdf alternative: If PyMuPDF is not suitable (rare edge cases), fall back to uv run --with pypdf python ... with the same pattern — pypdf.PdfWriter for merging, pypdf.PdfReader for reading
• pymupdf not installed: Automatically resolved via uv run --with pymupdf; no manual pip install needed