You already have an automated report pipeline that emits PDF invoices, contracts, or inspections. One day product asks: "Can we also drop in the photographer's JPG from the site visit, or the customer's signature image?" The conversion is trivial. The blast radius is not. A naive "merge the JPG into the PDF" solution leaks through to receipts, screen readers, and print drivers in ways that only show up weeks later.
This article is for the engineer who has to plug that requirement in today, not the document specialist who gets a week to plan it.
Calling this a "JPG to PDF conversion" is the first framing mistake. Almost no real product asks the user to upload JPGs and download a PDF. They ask for a PDF with JPG content embedded into an existing document, at a specific point in the layout, sized to a specific box, addressed at a specific audience. The conversion is a side-effect, not the deliverable.
In a production pipeline you generally face one of three flavors:
Each flavor has different failure modes, even though the file type looks the same. Conflating them is how teams ship a "working" feature that later fails a regulator's inspection.
For (1), most reporting stacks already have a rendering engine. If you are using Headless Chrome via Puppeteer or Playwright, you can simply emit an HTML document with <img src="https://cdn/.../photo.jpg">
and let the renderer place it. This preserves your existing typography and theming for free, which is the right default. The MDN reference for the HTML image element is worth bookmarking because browser PDF backends honor width
, height
, object-fit
, and ="lazy"
in slightly idiosyncratic ways that differ from screen rendering.
If the report is LaTeX (common for legal or academic PDFs), `graphicx`
with `\includegraphics[width=...]{photo.jpg}`
is the conventional path. Do not decode and re-encode the JPG to base64 inside the template; templating engines routinely truncate or rewrite long base64 strings, and the resulting PDF will silently embed a partial image.
For (2), bulk ingestion, a server-side library is safer than a browser automation loop. In Node, pdfkit
is a stable choice: you stream the JPG directly via image()
and call addPage()
per attachment, which keeps memory bounded. In Python, reportlab
's flowables
let you place images inline with text wrapping, which is what you usually want for "photo + caption + next photo." Both are well-suited for batch work because they do not require a display server.
For (3), PDF/A is a separate problem. You will need an external conformance checker such as `verapdf`
or PDFA-PIL
— the PDF/A specification on Wikipedia lists the profile levels and what they forbid. In practice the rule that bites most teams is font embedding: if your templating engine uses a webfont served from a CDN, the PDF will fail PDF/A validation because the font cannot be embedded legally. Plan a fallback font stack before you discover this in QA.
A few decisions look unimportant during the happy path and turn into tickets later:
Resolution vs. file size. A 12 MP phone JPG at full size inside a 4×3 inch print slot wastes roughly 11 MB per page and slows every downstream print spool. I default to long-edge 1600 px, JPEG q=82, which produces a 300–500 KB page image that prints crisply at 300 DPI. This is the same trade-off discussed in the JPEG specification on Wikipedia: quality 80–85 is the perceptual knee where file size drops sharply without visible loss for document photography.
Color management. Screenshots and product photos generally come in sRGB. Office printers and many archival workflows default to CMYK. If you do not embed an ICC profile, the print output is unpredictable; if you naively convert to CMYK at the same time, dark UI screenshots get crushed. For most document pipelines, embed the sRGB profile (sRGB IEC61966-2.1
) and let the printer translate.
Accessibility. Alt text and tagged structure do not exist by default in most PDF libraries. Screen readers like JAWS and NVDA read PDFs that follow the structure tree defined in PDF 1.7 specification, §14.7 (Tagged PDF), which is referenced by WCAG. If your PDF is delivered as a public artifact, add an alt description to each image as part of the generation step. pdfkit
's markContent
and reportlab
's canv.setTitle
plus flowable setLang
are a starting point, but full tagged PDF usually requires Apache PDFBox
or a commercial SDK.
Metadata hygiene. Strip GPS coordinates from phone photos before embedding. Most report platforms have no business handling user location. exiftool -all= photo.jpg
is the one-liner that satisfies your DPO and your QA lead in the same beat.
When a PR opens that adds image embedding, this is the list I run before merging. It catches roughly 80% of post-merge bugs.
width
and height
(or equivalent) so layout does not reflow on slow connections.sharp
, ImageMagick
, or Pillow, and store the optimized asset alongside the original.exiftool -overwrite_original -all= path/to/upload.jpg
.verapdf
.You do not need every step on day one. Skipping items 3 and 5 is fine for an internal-only dashboard; skipping 6 and 8 is rarely acceptable for customer-facing PDFs.
Synchronous vs. queue-driven. If you render a PDF synchronously inside a web request, an extra 800 KB image can push latency past your SLO. Move image optimization to a worker queue and render the PDF with already-optimized assets. This also lets you reuse a normalized thumbnail across other surfaces (emails, previews).
Caching and idempotency. Hashing the input JPG (SHA-256 of bytes) and using that as the asset key means a re-upload of the same photo does not trigger re-optimization, and the PDF rebuild is purely deterministic. This matters for invoices and signed contracts where "the same input produces the same output" is a regulatory expectation.
Reverse proxies and content sniffing. Some pipelines proxy image URLs through Cloudflare or a corporate gateway that re-encodes JPEGs. If your PDF renderer fetches the URL at request time, you may get a different file than the one you optimized. Either inline the bytes or store them in object storage with content-addressed keys.
Browser vs. server rendering. Browser-based PDF rendering is convenient and ugly for Q/A: the PDF output differs slightly per Chrome version, and headless Chrome on Linux tends to embed fonts that fail PDF/A validators on macOS. For anything compliance-bound, a server library is the more boring, more correct choice.
For a quick one-off conversion — for example, attaching a handful of JPGs to a one-page memo for a meeting in five minutes — a browser tool is fine and you can follow the in-house walkthrough on turning JPGs into a single PDF in your browser. Just do not let "the browser path worked once" become the design of the production system.
Sometimes the right answer is to refuse to bundle images into the PDF at all. If the consumer is going to print on a black-and-white office laser printer, attach the JPGs as a .zip
and put a single index page in the PDF — the photos will be unreadable printed anyway, and your PDF stays small and archivable. If the consumer is going to email the PDF, most email gateways already strip or compress inline images aggressively; a .zip
is more reliable. If the consumer is internal-only and the images are on a shared drive, put them in the right folder and skip the PDF entirely.
Knowing when the requirement is wrong is part of owning the pipeline.
No. Templating engines have truncation and escaping rules that can silently corrupt long base64 strings, producing partial images with no error. Store images on a CDN or S3, reference them by URL, and let the renderer fetch them at PDF-generation time.
For server-side bulk work, pdfkit
in Node and reportlab
in Python are both stable, well-documented, and avoid the font-embedding and version-drift issues of headless-browser rendering. For inline images inside a templated PDF already produced by Headless Chrome, an <img>
tag in the HTML is simpler and correct.
Run it through verapdf
for PDF/A conformance and through a screen reader such as NVDA. The cheapest CI check is verapdf --flavour 1b report.pdf
; if it passes and your alt strings are present, you are meeting the bulk of practical accessibility expectations.
For ad-hoc, manual, low-volume tasks where the output is not archived or audited — for example, a one-off memo or a meeting handout. For anything batched, customer-facing, or retention-bound, use a server-side library so output is deterministic, metadata is controlled, and auditing is possible. This article was drafted with AI assistance and reviewed for technical accuracy before publishing.