How to Add a Text Watermark to a PDF in Python

To add a text watermark to every page of a PDF in Python, draw the text on a one-page PDF with ReportLab, then merge that page into each source page with pypdf. Set over=False to put the watermark behind existing content; use over=True to put it in front. The example below creates an underlay watermark, writes a new output file, and keeps the source file unchanged.

1. Install the libraries

Use ReportLab to create the watermark page and pypdf to read, merge, and write PDFs. Install both in the Python environment that will run the script:

python -m pip install reportlab pypdf

Save the script as watermark.py next to input.pdf, then run python watermark.py. The full script is also suitable for adapting into a batch job. Library APIs can change, so pin tested package versions in a production environment and check the installed versions when diagnosing differences.

2. Add the same text watermark to every page

from io import BytesIO
from pathlib import Path

from reportlab.lib.pagesizes import letter
from reportlab.pdfgen import canvas
from pypdf import PdfReader, PdfWriter

INPUT = Path("input.pdf")
OUTPUT = Path("output-watermarked.pdf")
WATERMARK_TEXT = "CONFIDENTIAL"

if not INPUT.is_file():
    raise FileNotFoundError(f"Input PDF not found: {INPUT}")

# Create a one-page PDF in memory. ReportLab coordinates are in points,
# with (0, 0) at the bottom-left of the page.
watermark_buffer = BytesIO()
watermark_canvas = canvas.Canvas(watermark_buffer, pagesize=letter)
watermark_canvas.setFont("Helvetica", 36)
watermark_canvas.setFillColorRGB(0.55, 0.55, 0.55)
watermark_canvas.drawString(72, 72, WATERMARK_TEXT)
watermark_canvas.showPage()
watermark_canvas.save()
watermark_buffer.seek(0)

watermark_page = PdfReader(watermark_buffer).pages[0]
reader = PdfReader(str(INPUT))
if reader.is_encrypted:
    raise ValueError("The input PDF is encrypted; decrypt it before watermarking.")
if not reader.pages:
    raise ValueError("The input PDF has no pages.")

writer = PdfWriter()
for page in reader.pages:
    page.merge_page(watermark_page, over=False)
    writer.add_page(page)

with OUTPUT.open("wb") as output_file:
    writer.write(output_file)

print(f"Wrote {OUTPUT}")

The watermark is placed 72 points from the left and bottom edges. PDF points are 1/72 of an inch. ReportLab’s canvas uses a lower-left origin and Cartesian coordinates, so increasing the x coordinate moves right and increasing y moves up. The pypdf guide describes the same merge operation for stamps and watermarks; the over setting determines which content layer appears above the other. pypdf: Adding a Stamp/Watermark · ReportLab User Guide.

3. Choose background or foreground

For a conventional watermark that sits behind text and graphics, pass over=False:

page.merge_page(watermark_page, over=False)

For a visible stamp on top of page content, set over=True or omit the argument where the API’s default is overlay behavior:

page.merge_page(watermark_page, over=True)

This changes drawing order; it does not guarantee that the watermark will be readable over every background. A pale underlay can disappear behind a dark image, while a foreground stamp can obscure small print. Choose color, opacity, and layer order based on the document’s content and inspect representative pages in the PDF viewers used by your audience.

4. Center, scale, or rotate the watermark

For anything other than the watermark page’s default placement, use merge_transformed_page with a pypdf Transformation. The transformation can scale, translate, or rotate the watermark page as it is merged. For example, this places a half-size watermark page with a translation:

from pypdf import Transformation

page.merge_transformed_page(
    watermark_page,
    Transformation().scale(0.5).translate(tx=100, ty=150),
    over=False,
)

To rotate it, add a rotation to the transformation. Transformation methods compose, so check the resulting placement on a sample page when combining rotation, scale, and translation:

page.merge_transformed_page(
    watermark_page,
    Transformation().rotate(45).scale(0.5).translate(tx=100, ty=150),
    over=False,
)

Coordinates and page boxes affect where content lands. When the source page has rotation metadata and the merged result appears incorrectly oriented, pypdf recommends applying transfer_rotation_to_content() to that source page before merging. This transfers the rotation into the page content and adjusts its page boxes. Check the result after making this change, especially when the document has unusual crop or media boxes.

for page in reader.pages:
    page.transfer_rotation_to_content()
    page.merge_page(watermark_page, over=False)
    writer.add_page(page)

5. Handle different page sizes

The minimal script creates a US Letter watermark page. That is convenient when all destination pages have matching geometry, but a single fixed-size watermark page may not place text consistently across A4, landscape, or mixed-size documents. Inspect each page’s mediabox and make the watermark page match its target geometry, or transform the watermark to fit. A page’s visible crop can also differ from its media box.

A practical production approach is to generate a small watermark PDF for each distinct page size, cache those generated pages during the job, and merge the matching one onto each source page. If pages have a variety of sizes, calculate position from each target page’s width and height rather than hard-coding Letter coordinates. For example, to draw near the lower-left corner, use a margin measured from that page’s box. Remember that ReportLab’s coordinate origin is at the lower-left.

6. Set font, color, and transparency

Use the ReportLab canvas to control the text before saving the watermark PDF. setFont controls the font face and size; setFillColorRGB sets an RGB fill color. The example uses the built-in Helvetica font. If your watermark contains characters outside the selected font’s coverage, register and use a font that includes those glyphs, then inspect the output in more than one viewer.

Some ReportLab canvas versions expose setFillAlpha for fill transparency. Availability is version-dependent, so confirm it in the installed version rather than assuming it exists:

if hasattr(watermark_canvas, "setFillAlpha"):
    watermark_canvas.setFillAlpha(0.25)

watermark_indices = {0, 2, 4}  # first, third, and fifth pages

for index, page in enumerate(reader.pages):
    if index in watermark_indices:
        page.merge_page(watermark_page, over=False)
    writer.add_page(page)

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)