Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python pypdf Metadata and Watermarks

Read and write PDF metadata and add watermarks with Python pypdf. Includes code for page positioning, rotated pages, and error handling.

~3 min readPython
#pypdf#PDF metadata#watermarking#PDF manipulation
Illustration of a PDF document with a watermark overlay and metadata tags, representing Python pypdf operations.

When you need to handle PDF metadata and watermarks in Python, pypdf is a common choice. This article shows how to read and update document metadata and how to overlay a watermark on every page. The examples use pypdf's reader and writer APIs, which are pure Python and work across platforms.

Reading PDF Metadata with pypdf

The PdfReader class exposes document-level metadata through the .metadata attribute. This attribute is a dictionary-like object that maps PDF Info keys to their values. Common keys include /Title, /Author, /Subject, /Creator, /Producer, and date fields. To read them:

python
from pypdf import PdfReader reader = PdfReader("input.pdf") meta = reader.metadata if meta: print(meta.title) # or meta["/Title"] print(meta.author) print(meta.subject)

The metadata object supports both attribute access and dictionary-style access with the leading slash. Not all keys are guaranteed to be present, and a PDF may have no metadata at all, so check for None before reading and use .get() when you need a default value.

Writing and Updating Metadata

To write or update metadata, create a PdfWriter, copy pages from the reader, and call add_metadata(). The keys must include the leading slash:

python
from pypdf import PdfReader, PdfWriter reader = PdfReader("input.pdf") writer = PdfWriter() writer.append_pages_from_reader(reader) writer.add_metadata({ "/Title": "Updated Title", "/Author": "Jane Doe", "/Subject": "Technical guide" }) with open("output.pdf", "wb") as f: writer.write(f)

If you want to preserve the original metadata, copy it from the reader before adding changes:

python
if reader.metadata: writer.add_metadata(reader.metadata) writer.add_metadata({"/Title": "New Title"})

The second call overrides the title while keeping other fields.

Adding a Watermark to Every Page

A common watermarking approach is to merge a single watermark page onto each page of the source document. The merge_page() method overlays the watermark page's content onto the target page using the same coordinate origin. If the watermark page is the same size as the source page, the overlay covers the full page. If it is smaller, the content appears near the lower-left corner by default. A larger watermark page is clipped to the target page's visible area.

python
from pypdf import PdfReader, PdfWriter reader = PdfReader("input.pdf") watermark = PdfReader("watermark.pdf").pages[0] writer = PdfWriter() for page in reader.pages: page.merge_page(watermark) writer.add_page(page) with open("watermarked.pdf", "wb") as f: writer.write(f)

This basic pattern does not resize the watermark, so you will usually need to scale and position it.

Controlling Watermark Size and Position

To control where the watermark appears, use merge_transformed_page() with a Transformation. The transformation can scale, translate, and rotate the watermark. For example, to scale a watermark to 50% of the largest size that fits on a page and center it:

python
from pypdf import PdfReader, PdfWriter, Transformation reader = PdfReader("input.pdf") watermark_page = PdfReader("watermark.pdf").pages[0] writer = PdfWriter() for page in reader.pages: page_width = float(page.mediabox.width) page_height = float(page.mediabox.height) wm_width = float(watermark_page.mediabox.width) wm_height = float(watermark_page.mediabox.height) scale = min(page_width / wm_width, page_height / wm_height) * 0.5 tx = (page_width - wm_width * scale) / 2 ty = (page_height - wm_height * scale) / 2 transformation = Transformation().scale(scale, scale).translate(tx, ty) page.merge_transformed_page(watermark_page, transformation) writer.add_page(page) with open("watermarked.pdf", "wb") as f: writer.write(f)

The 0.5 factor makes the watermark half the size it would be if it filled the page. Adjust the scale and translation values to place the watermark anywhere.

Handling Rotated Pages and Page Sizes

PDF pages can have a rotation attribute of 0, 90, 180, or 270 degrees. When you merge a watermark onto a rotated page, the watermark is applied in the page's coordinate space, so it may appear rotated relative to the viewer. To compensate, rotate the watermark by the opposite of the page rotation.

Because methods like rotate_clockwise() mutate the page object, do not call them on the same shared watermark page inside a loop. Instead, create a separate watermark page for each rotation value or include the rotation in a per-page Transformation.

If the document contains pages of different sizes, calculate the scale and translation inside the page loop using each page's own dimensions, as in the previous example.

Performance and Memory Considerations

pypdf is not a streaming PDF library. A PdfReader keeps parsed objects in memory, and a PdfWriter accumulates pages until write() is called. For very large PDFs this can use significant memory, so test with a representative file before watermarking a huge document. After merging, each page's content stream contains the watermark content, so repeated merges can increase output size and memory use.

Error Handling and Compatibility

pypdf raises PdfReadError when it encounters a malformed PDF. For encrypted files, pass the password when creating the reader:

python
reader = PdfReader("encrypted.pdf", password="secret")

If the password is wrong or missing when one is required, pypdf raises FileNotDecryptedError. Wrap file operations in try/except blocks to handle missing files and permission errors.

When writing metadata, remember that some PDF viewers ignore non-standard keys, and date fields should follow the PDF date format. If you create a new writer, you must explicitly copy metadata from the reader; otherwise, the output PDF will have no metadata. Watermarking does not alter the original file; you always write a new output file, which is the safest approach for preserving the source document.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.