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.

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:
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:
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:
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.
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:
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:
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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.