Skip to content
Tutorials Center
My learning

Topics

Lesson 67 of 149 ยท Files and Errors

PDF Files with pypdf

Work with PDF files in Python using pypdf. Extract text, merge, split, rotate and reorder pages, edit metadata, add a watermark and encrypt a PDF. Runs live.

PDF is the format people use when a document must look the same everywhere: invoices, contracts, reports, scanned forms. Programs often need to look inside those files. You may want to pull the text out of a hundred invoices, glue monthly reports into one file, split a scanned book into chapters, or stamp "DRAFT" across every page.

Python does this well with pypdf, a pure-Python library for reading and changing PDFs. In this lesson you'll create PDFs with a second library (reportlab, so we have something to work on), then read text, merge, split, rotate, reorder, edit metadata, overlay a watermark and encrypt a file.

Installing. pypdf and reportlab are not in the standard library. On your computer, run python -m pip install pypdf reportlab (preferably inside a virtual environment). The live examples install them with micropip, the in-browser equivalent of pip, and keep every PDF in memory with io.BytesIO. On your computer you would pass file names instead: PdfReader("report.pdf") and writer.write("out.pdf"). The first run on a page downloads the packages, so it takes a few seconds.

What a PDF really is

A PDF is not a stream of text like a text file. It is a collection of pages, and each page is a list of drawing instructions: "put these glyphs at this position with this font". There are no paragraphs, no table cells and no reading order stored in the file, only positioned pieces of text. That explains most surprises later. Extracting text means reconstructing a plausible order from the positions, and it works well for ordinary documents and badly for complicated layouts.

Two more facts matter:

  • A scanned PDF contains pictures of pages, not text. pypdf finds no text in it. You need OCR (optical character recognition) software for those, which is a different tool.
  • pypdf works on pages as units. It can move, copy, rotate and combine pages and change metadata, but it is not a layout editor. To change a sentence inside a page, regenerate the page with a tool like reportlab.

Creating a sample PDF

To practice, we need PDFs. The helper below builds one in memory with reportlab: each entry is a title plus lines of text, and each entry becomes a page. You don't need to understand reportlab's drawing calls in detail. drawString(x, y, text) places text, measured in points (1/72 inch) from the bottom-left corner of the page. An A4 page is about 595 by 842 points.

Python Build a PDF and read it back

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

PdfReader accepts a file path, an open binary file, or any file-like object such as io.BytesIO. reader.pages behaves like a list: it has a length, supports indexing and slicing, and can be looped over. page.extract_text() returns one string per page; lines are separated by \n.

On your computer the read side is just:

Python
from pypdf import PdfReader

reader = PdfReader("invoice.pdf")
text = "\n".join(page.extract_text() for page in reader.pages)

Searching and cleaning extracted text

Extracted text is plain str, so everything you know about strings and regular expressions applies. A typical job is finding which pages mention a word, or pulling a value out of every document.

Python Find text and pull out values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real PDFs are messier than ones you generate yourself. Words can break at line ends, columns can interleave, and some fonts produce odd characters. Always print a sample of the extracted text before building a parser on top of it, and keep your regular expressions tolerant of extra spaces and line breaks.

If extract_text() returns an empty string for a page that clearly has words on screen, the page is probably a scanned image. Use an OCR tool such as Tesseract (through a library like pytesseract) instead of pypdf.

Merging, splitting, rotating and reordering

Changing a PDF means building a new one. You create a PdfWriter, add pages taken from one or more readers, and write the result. Pages are not copied as text; they keep their exact appearance.

Python Merge, split, rotate and reorder pages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A few points to remember:

  • writer.append(reader) adds every page of another document. Pass pages=(0, 2) (a (start, stop) tuple) or a list of page numbers to take only some of them.
  • writer.add_page(page) adds a single page object. Keep the reader alive until you have written the output.
  • page.rotate(angle) takes a multiple of 90 and turns the page clockwise. It changes the page's display rotation, not its content.
  • Page numbers in pypdf start at 0, like list indexes, while people count from 1. Convert at the edges of your program.
  • Writing to io.BytesIO is handy for tests and web uploads. With a real file, open it in binary mode ("wb") or pass the file name to writer.write(...).

Metadata and encryption

Every PDF carries a small dictionary of metadata (title, author, creation date). You can read it from reader.metadata and set it on the writer. You can also protect a file with a password.

Python Edit metadata and encrypt a PDF

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

decrypt() returns 0 when the password is wrong and a non-zero value when it works, so test it before reading pages. The live example uses the older RC4 algorithm because it needs no extra package. On your computer, install cryptography (pip install cryptography) and use encrypt("password"), which defaults to strong AES-256. Prefer AES for anything that matters, and treat RC4 as obsolete.

Never hard-code real passwords in source code, and don't assume a password-protected PDF is secure against a determined attacker unless it uses AES. A PDF password is an access barrier, not a substitute for proper encryption of sensitive files.

Adding a watermark

Stamping every page with the same overlay (a watermark, a letterhead, a page number) is a classic task. The recipe: create a one-page PDF containing the stamp, then add each target page to the writer and merge the stamp page on top of it with merge_page(). Add the page first: recent pypdf versions refuse to modify pages that do not belong to a writer.

Python Stamp DRAFT on every page

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The output shows both the original line and the word DRAFT for each page, which proves the stamp is part of the page. Because the stamp is just another drawing instruction layered on top, the original text is still selectable and extractable. A watermark does not hide or redact anything beneath it.

Common mistakes

  • Treating scanned PDFs as text. No text layer means empty strings. Check len(text.strip()) and fall back to OCR or report the problem.
  • Forgetting 0-based page numbers. reader.pages[0] is the first page.
  • Writing the output to the file you are still reading. Write to a new name, then replace the original once the program has succeeded.
  • Assuming extracted text keeps layout. Tables come out as rows of words. For heavy table extraction, look at tools built for it, such as pdfplumber.
  • Opening files in text mode. PDFs are binary. Use "rb" and "wb".
  • Trusting untrusted PDFs. Files from the internet can be malformed on purpose. Handle pypdf.errors.PdfReadError (see exceptions) and never run anything the file "asks" for.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does extract_text() return an empty string for some PDFs that show words on screen?

    A scanned PDF stores each page as an image. There is no text to extract, so you need OCR software to turn the picture into text.
  2. 2. Which object do you use to build a new PDF from pages of existing files?

    PdfWriter collects pages with add_page() or append() and writes them out with write(). PdfReader is for reading.
  3. 3. How do you take the second, third and fourth pages of reader (counting from 1 as a person would)?

    Page indexes start at 0, so the second page is index 1. A slice stops before its end index, so pages 2 to 4 are reader.pages[1:4].
  4. 4. What does a watermark added with merge_page() do to the text underneath it?

    merge_page() layers the stamp's drawing instructions on top of the page. The original instructions are untouched, so a watermark is no way to redact information.

Summary

  • A PDF is a set of pages made of positioned drawing instructions, not flowing text; scanned PDFs hold only images.
  • PdfReader opens a path or file-like object; reader.pages is list-like (0-based) and page.extract_text() returns a string you can search with regular expressions.
  • PdfWriter builds new files: append() merges documents, add_page() adds single pages, slicing and reordering give splits and rearrangements, page.rotate(90) turns a page.
  • add_metadata() sets title and author; encrypt() and decrypt() handle passwords (prefer AES, which needs the cryptography package).
  • merge_page() overlays a stamp or letterhead, but it does not hide what lies beneath.
  • Open and write PDFs in binary mode, keep readers alive until you write, and handle read errors for untrusted files.

Next: Browser Automation with Selenium and Playwright, for programs that drive a real web browser.