How to Add an Image Watermark to a PDF in Ruby

Use "stamp" instead of "background" to place the mark above existing content. Keep input and output paths distinct while developing the workflow, and make the destination directory writable. In a job runner, capture standard output and standard error so an operator can inspect the command’s diagnostic message.

4. Put an image on pages you generate with Prawn

If you are creating the PDF yourself, Prawn can draw the image in the page-generation block. Install the gem and save this as make_pdf.rb:

# Gemfile: gem "prawn"
require "prawn"

logo = "logo.png"
Prawn::Document.generate("report.pdf", page_size: "A4") do |pdf|
  pdf.repeat(:all) do
    pdf.image logo, at: [420, 790], width: 90
  end

  pdf.text "Report content starts here", at: [50, 730]
  pdf.start_new_page
  pdf.text "Second page content", at: [50, 730]
end

Run it with bundle exec ruby make_pdf.rb after adding Prawn to your Gemfile and running bundle install. Prawn’s image method adds an image to the current page and supports JPG and PNG. If only width or height is given, it scales proportionally; if both are given, it stretches to fit both dimensions. See the Prawn image API documentation.

The coordinates in Prawn are points measured from the page’s lower-left origin. Adjust at and width for your page size and desired placement. The repeat(:all) block draws the logo on every page, including pages created after the block is declared. For a single page, call pdf.image directly in the page body instead. Use proportional sizing if the logo’s aspect ratio must stay intact.

5. Overlay a prepared watermark page with CombinePDF

When the logo is already in a one-page PDF, CombinePDF’s documented pattern imports its first page and appends it to every page in the source document:

# Gemfile: gem "combine_pdf"
require "combine_pdf"

watermark_page = CombinePDF.load("watermark.pdf").pages[0]
pdf = CombinePDF.load("input.pdf")
pdf.pages.each do |page|
  page << watermark_page
end
pdf.save("output.pdf")

This example overlays the imported page. The project documentation describes the page-level << operator and warns that it is the page, not the PDF object, that receives the overlay. See the CombinePDF project documentation. That repository currently identifies the project as unmaintained, which is a maintenance consideration when selecting it for a new application.

6. Verify the output before distributing it

1. Open the output in at least one PDF viewer and confirm that the watermark is visible on the intended pages.
2. Check both a page with ordinary content and pages with unusual rotation, annotations, transparency, forms, or other interactive elements.
3. Verify that the logo is not stretched, cropped, too faint, or obscuring text. Adjust image dimensions or placement in the watermark PDF and regenerate it if necessary.
4. Check page count and file readability after processing. Keep a copy of the source so you can rerun the transformation if you change the watermark.
5. If the source is encrypted, use the documented password option and ensure your process handles the password appropriately.

PDF libraries and commands do not guarantee that every document feature will be preserved in every case. The research documentation specifically calls out annotations, page rotation, encryption, forms, transparency, and incremental-update behavior as areas that can affect output. Test documents representative of your actual workload; do not infer preservation from a successful command exit alone.

Or skip the browser setup

For web-page screenshots, ScreenshotNeo provides a one-request screenshot API and an MCP server for AI agents. This is a separate task from adding a watermark to an existing PDF: the API captures a URL as an image or PDF. The API accepts a URL and returns a clean screenshot, in PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.

Configuration, reliability, and cost considerations

• Overlay order: choose background to place the mark beneath page content or stamp to place it above. A background can become hidden by opaque page artwork; a stamp may cover text.
• Page mapping: specify watermark pages with -i. The default repeat behavior reuses the last selected page; choose -r all for cyclic repetition.
• Image format: Prawn supports JPG and PNG. PNG is a practical choice when the logo needs transparency. Prawn documents note that PNGs with alpha channels can be processor- and memory-intensive.
• Geometry: use the same intended page dimensions and coordinate system when making the watermark page. Check rotated or differently sized source pages, as a mark positioned for one geometry may not land where expected on another.
• Memory and throughput: the dossier provides no benchmark for these libraries. Large PDFs and high-resolution transparent images can consume more resources; measure with representative files and process work in bounded jobs.
• Licensing: HexaPDF documents AGPL and commercial licensing options. Review its current license terms for proprietary distribution. Do not choose a dependency solely from an example that happens to run locally.
• Cost: these Ruby libraries are software dependencies rather than per-document screenshot services. Account for infrastructure, operational maintenance, and any applicable license terms; no throughput or cost-per-page benchmark is claimed here.

Troubleshooting

FAQ

Can I add a PNG directly to an existing PDF with Prawn?

Prawn’s image method is for pages in PDFs you generate. For an existing document, prepare a watermark PDF page and apply it with HexaPDF, or use a suitable existing-PDF workflow such as the documented CombinePDF overlay.

How do I put the logo on every page?

With HexaPDF, the default command applies its first watermark page to all input pages. With Prawn, place the image in a repeat(:all) block. With CombinePDF, iterate over pdf.pages and append the imported watermark page.

Should a watermark be a background or a stamp?

Use a background when it should sit behind content and a stamp when it should sit above. Check the result on real pages because either choice can reduce legibility depending on the artwork.

Will watermarking preserve digital signatures?

The supplied documentation does not claim universal preservation of signatures or other PDF features. Validate the output against your document requirements and signing workflow.