The document is wrong
The generated PDF is far too large
A three-page invoice comes out at eight megabytes. Email gateways reject it, storage costs climb, and the recipient waits to open it.
What is actually happening
Almost always images at their source resolution. A photo straight from a phone is several thousand pixels wide, and putting it in a box 200 pixels across does not resize the file, only the display. The second cause is embedding a full font family when the document uses one weight.
Confirming it is this and not something that looks like it
Divide the file size by the number of images. If it is roughly the size of your source images, that is the whole answer.
The fix
Resize images to the resolution they will actually be printed at before embedding them, and subset fonts to the characters the document uses. For print, three times the CSS pixel width is more than enough; beyond that you are storing detail no printer will reproduce.
from PIL import Image
def for_document(source: Image.Image, css_px_width: int) -> Image.Image:
"""Three times the display width covers print resolution. Anything past that
is bytes nobody will ever see."""
target = css_px_width * 3
if source.width <= target:
return source
ratio = target / source.width
return source.resize((target, round(source.height * ratio)), Image.LANCZOS)If that was not it
These produce the same symptom often enough to be worth ruling out before assuming the fix above did not work.
- Fonts embedded in full rather than subset to the glyphs used
- A background image repeated on every page, embedded once per page by some pipelines
- PNG used for photographs, where JPEG or WebP would be a fraction of the size
- Vector graphics with tens of thousands of path nodes, common in exported maps
Frequently asked
Does this happen with every rendering engine?
The behaviour behind it is not specific to one tool. Almost always images at their source resolution. Anything rendering HTML to a paged medium has to make the same decision, so the fix travels with you if you change how the render happens.
Will this show up as an error in my logs?
No, and that is what makes it expensive. A document that renders wrong is still a successful render as far as every log line is concerned. It is found by someone opening the file, which is usually the customer.
Related failures
Problems people arrive at from the same starting point, or mistake for this one.
The generated PDF is blank
Almost always one of three things: the content is rendered by JavaScript that had not run when the snapshot was taken, the body has no height because everything inside it is absolutely positioned or floated, or the markup you sent was empty because the template call returned before the data arrived..
Background colours and images are missing from the PDF
Browsers drop backgrounds when printing, because a page with every background painted would empty a toner cartridge, and most render APIs inherit that default.
Images do not appear in the PDF
The image src is a path rather than a URL.
The PDF ignores my CSS
The stylesheet is linked rather than embedded, and the link points somewhere the renderer cannot reach: a bundler-generated path, a digested asset filename, or a URL behind your application's authentication.
Content rendered by JavaScript is missing from the PDF
The snapshot was taken before the script finished.
CSS for paged documents, and what actually works
Which parts of the paged media specification a browser-based render implements.
Everything that goes wrong, by category
The full list, grouped by where in the pipeline it breaks.
Paste your markup and see the rendered document, without signing up.