Setup

pypdf is pure Python with no system dependencies, so it installs cleanly anywhere:

pip install pypdf

Every recipe below uses the same two classes. PdfReader opens the source and PdfWriter builds each output file. Pages are copied structurally, not re-rendered, so text stays selectable and image quality doesn't change.

One thing to keep in mind is that pypdf indexes pages from zero, while people count from one. I keep everything 1-based at the edges (arguments, filenames) and convert in one place, because mixing the two is where off-by-one bugs come from.

Recipe 1: one file per page

from pathlib import Path
from pypdf import PdfReader, PdfWriter

def split_every_page(src: str, out_dir: str = "pages") -> None:
    reader = PdfReader(src)
    out = Path(out_dir)
    out.mkdir(exist_ok=True)
    width = len(str(len(reader.pages)))
    for i, page in enumerate(reader.pages, start=1):
        writer = PdfWriter()
        writer.add_page(page)
        with open(out / f"page-{i:0{width}d}.pdf", "wb") as f:
            writer.write(f)

split_every_page("input.pdf")

The width trick zero-pads filenames (page-007.pdf rather than page-7.pdf) so they sort correctly in a file manager and in ls. It's a small detail, but whoever receives a folder of 300 pages will notice it.

Recipe 2: custom ranges

This is the request I get most often. I let people write ranges the way they'd type them in a print dialog, such as 1-4,5-12,13-end, and turn each comma-separated piece into its own file.

from pypdf import PdfReader, PdfWriter

def parse_ranges(spec: str, total: int) -> list[tuple[int, int]]:
    ranges = []
    for part in spec.split(","):
        part = part.strip()
        if "-" in part:
            start, end = part.split("-", 1)
            start = int(start)
            end = total if end.strip().lower() == "end" else int(end)
        else:
            start = end = int(part)
        if not (1 <= start <= end <= total):
            raise ValueError(f"Bad range {part!r} for a {total}-page file")
        ranges.append((start, end))
    return ranges

def split_ranges(src: str, spec: str) -> None:
    reader = PdfReader(src)
    for start, end in parse_ranges(spec, len(reader.pages)):
        writer = PdfWriter()
        for n in range(start - 1, end):  # convert to 0-based here only
            writer.add_page(reader.pages[n])
        with open(f"pages-{start}-{end}.pdf", "wb") as f:
            writer.write(f)

split_ranges("input.pdf", "1-4,5-12,13-end")

The validation matters more than it looks. Without it, a typo like 12-5 quietly produces an empty file, and someone emails a blank PDF to their accountant.

Recipe 3: fixed-size chunks

Upload portals often cap file size or page count. Splitting into chunks of N pages is a quick way under the limit:

from pypdf import PdfReader, PdfWriter

def split_chunks(src: str, size: int = 10) -> None:
    reader = PdfReader(src)
    total = len(reader.pages)
    for start in range(0, total, size):
        writer = PdfWriter()
        for n in range(start, min(start + size, total)):
            writer.add_page(reader.pages[n])
        with open(f"part-{start // size + 1}.pdf", "wb") as f:
            writer.write(f)

split_chunks("input.pdf", size=10)

If the limit is in megabytes rather than pages, chunking by page count is only an approximation. A single scanned page can be bigger than fifty pages of text. In that case I compress first and split second.

Recipe 4: one file per top-level bookmark

This is the most useful recipe and the least well known. Many long PDFs (reports, manuals, books exported from Word) have an outline, the bookmark panel in a PDF viewer. pypdf exposes it as reader.outline, a list where nested lists hold child bookmarks. Top-level entries are usually chapters.

import re
from pypdf import PdfReader, PdfWriter

def split_by_bookmarks(src: str) -> None:
    reader = PdfReader(src)
    total = len(reader.pages)
    # Top-level items only; nested lists are sub-bookmarks.
    marks = [
        (item.title, reader.get_destination_page_number(item))
        for item in reader.outline
        if not isinstance(item, list)
    ]
    if not marks:
        raise ValueError("This PDF has no bookmarks")
    marks.sort(key=lambda m: m[1])
    for idx, (title, start) in enumerate(marks):
        end = marks[idx + 1][1] if idx + 1 < len(marks) else total
        if end <= start:
            continue  # two bookmarks pointing at the same page
        writer = PdfWriter()
        for n in range(start, end):
            writer.add_page(reader.pages[n])
        safe = re.sub(r"[^\w\- ]", "", title).strip() or f"section-{idx + 1}"
        with open(f"{idx + 1:02d} {safe}.pdf", "wb") as f:
            writer.write(f)

split_by_bookmarks("manual.pdf")

A few things I learned the hard way:

• Bookmarks aren't always in page order. Sorting by start page avoids negative ranges.
• Two bookmarks can point to the same page. The end <= start check skips the empty section instead of writing a zero-page file.
• Titles contain characters filenames can't. Slashes, colons and question marks show up constantly in chapter names, so they get stripped.
• Pages before the first bookmark are dropped. If the cover and table of contents matter, add a ("Front matter", 0) entry when the first bookmark doesn't start at page 0.

Encrypted files

If a PDF has an open password, pypdf can't read its pages until you decrypt it:

reader = PdfReader("locked.pdf")
if reader.is_encrypted:
    reader.decrypt("the-password")

For AES-encrypted files, pypdf needs a crypto backend: pip install pypdf[crypto]. Files with only an owner password (the kind that restricts printing or editing) usually open with decrypt(""). Whether you should split them is a question for whoever owns the document.

Keeping output files small

When you copy pages into a new writer, pypdf brings along the resources each page references, such as fonts and images. If several pages share a large image, each split file gets its own copy, which is correct because every file has to stand alone. But it means the total size of the parts can be well above the original. That's expected, not a bug.

If an individual part is still too big, run writer.compress_identical_objects() before writing (available in recent pypdf versions), or pass the output through a dedicated compression step.

Making it a command-line tool

Once I had these functions, I wrapped them in a small CLI so nobody on the team had to edit Python to change a range. argparse from the standard library is enough:

import argparse

parser = argparse.ArgumentParser(description="Split a PDF")
parser.add_argument("src")
group = parser.add_mutually_exclusive_group(required=True)
group.add_argument("--ranges", help="e.g. 1-4,5-12,13-end")
group.add_argument("--chunk", type=int, help="pages per file")
group.add_argument("--bookmarks", action="store_true")
args = parser.parse_args()

if args.ranges:
    split_ranges(args.src, args.ranges)
elif args.chunk:
    split_chunks(args.src, args.chunk)
else:
    split_by_bookmarks(args.src)

Put it in the same file as the functions above, and python split.py report.pdf --ranges 1-4,13-end does what you'd expect. The mutually exclusive group means argparse rejects ambiguous calls with a clear error, so the script doesn't have to guess which mode you meant. In my experience that matters more than any extra feature: the people who use a tool like this run it once a month and don't remember the details, so a clear refusal beats a silent wrong guess every time.

When a script is overkill

All of this is worth it when splitting is part of a pipeline: monthly statements, generated reports, batch jobs on a server. For a one-off ("I just need pages 3 to 7 of this contract"), writing Python is slower than just doing it. I wrote a longer walkthrough on splitting PDFs with Python on the OneFileKit blog, which also covers the no-code options for people who'd rather not open a terminal.

Wrapping up

• PdfReader plus a fresh PdfWriter per output file covers almost every split.
• Keep page numbers 1-based for humans and convert to 0-based in exactly one place.
• Validate ranges, because silent empty files are worse than errors.
• reader.outline with get_destination_page_number() gets you per-chapter splits for free.

If you've got a weirder splitting requirement than "one file per bookmark", tell me in the comments. I collect them.