What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
When CSS boxes, text, or images look smaller in a wkhtmltopdf PDF, the usual cause is not a single broken CSS rule. WebKit may be shrinking the page to fit its printable width, while paper size, margins, viewport width, print media, DPI, zoom, and the operating system independently change the result. Start by recording your exact binary and environment, then compare a controlled fixture with and without smart shrinking before changing zoom or DPI.
What “scaling down” means in wkhtmltopdf
wkhtmltopdf renders HTML in an older WebKit engine and lays that rendered page onto a PDF page. A CSS length such as 100px is therefore affected by the relationship between the virtual page, the printable content area, and the selected output geometry. The CLI documentation describes smart shrinking as WebKit’s strategy that makes the pixel-to-DPI ratio non-constant; libwkhtmltox describes intelligent shrinking as fitting more content on a page.
Separate these symptoms before changing settings:
- Uniform reduction: nearly every element is smaller by a similar factor. Smart shrinking, zoom, or DPI is likely involved.
- Only the right side is cut off: the content is too wide for the usable page area. Disabling shrinking may have exposed this rather than fixed it.
- Different layout at different widths: responsive CSS, scrollbars, or a changed viewport is selecting another rule.
- Different output on two machines: compare binary builds, patched-Qt status, operating system, fonts, and command-line defaults.
There is no universal “CSS scale” multiplier that guarantees a 1:1 HTML-to-PDF result on every platform.
1. Record the renderer and make a reproducible fixture
Capture the environment first
Save the exact output of wkhtmltopdf --version, operating-system and version, wrapper or library version, complete command line, and whether the executable is a patched-Qt build. The project’s support guidance requests these details together with a duplicating HTML/CSS/JS test case. This matters because a reported wkhtmltopdf 0.12.1 patched-Qt case produced different A4 dimensions on Windows and Linux; that report demonstrates why environment comparison is necessary, not that every pair of systems behaves differently.
Recommended Free Tools
#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Use a small, measured HTML file
Do not debug a production stylesheet while changing several flags. Create a fixture that labels known dimensions and uses a paper-sized outer box. For example:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
html, body { margin: 0; padding: 0; }
.sheet { width: 210mm; min-height: 297mm; box-sizing: border-box;
border: 1px solid #000; padding: 10mm; }
.box { width: 100mm; height: 50mm; border: 1px solid #c00;
font: 16px/1.4 Arial, sans-serif; }
@media print { .print-marker { display: block; } }
@media screen { .print-marker { display: none; } }
</style>
</head>
<body>
<div class="sheet">
<div class="box">100mm × 50mm test box</div>
<p class="print-marker">Print media is active.</p>
</div>
</body>
</html>Measure the resulting PDF with a PDF viewer or a known reference object. Keep this file unchanged while testing one variable at a time.
2. Verify page geometry before changing scale
Paper size and margins define the usable content rectangle. A4 with large margins can be narrower than an A4-sized CSS container, causing WebKit to shrink the whole layout. Check:
- paper size (
--page-size A4or explicit width and height); - orientation;
- left, right, top, and bottom margins;
- any CSS page rules or fixed-width wrappers that exceed the printable area.
Run an explicit baseline rather than relying on wrapper defaults:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →wkhtmltopdf --page-size A4 --margin-top 10mm --margin-right 10mm
--margin-bottom 10mm --margin-left 10mm input.html baseline.pdfIf the PDF’s paper dimensions are wrong, changing --zoom only hides the geometry error. Make the physical page and CSS design agree first.
3. Test smart shrinking as a controlled comparison
What the option does
Smart shrinking is enabled by default in the CLI documentation. It allows WebKit to reduce the rendered scale so more content fits on the page. That can make CSS dimensions appear smaller.
Run both versions
wkhtmltopdf --page-size A4 --print-media-type input.html output-default.pdf
wkhtmltopdf --page-size A4 --disable-smart-shrinking
--print-media-type input.html output-no-shrink.pdfCompare the labeled 100 mm box, text size, and right edge. Disabling the option is a diagnostic, not a guaranteed fix. A report using wkhtmltopdf 0.12.4 on Windows Server 2012 R2 describes output becoming too wide and clipping on the right after smart shrinking was disabled. Conversely, a 2020 comment says disabling it helped one wkhtmltopdf 0.12.6 deployment in Node.js Lambda. Those are environment-specific reports, not compatibility guarantees.
If disabling it clips content
Keep shrinking enabled and reduce the actual cause of overflow: make the CSS width fit the printable area, reduce margins, select the correct paper size, or set an appropriate viewport. Do not compensate by randomly multiplying every CSS dimension.
4. Set the viewport deliberately
--viewport-size emulates a browser window size and is particularly relevant when CSS overflow, custom scrollbars, or responsive breakpoints affect layout. A narrow default viewport can activate mobile rules; a wide one can make a fixed desktop layout overflow the paper.
wkhtmltopdf --page-size A4 --viewport-size 1280x900
--print-media-type input.html output-viewport.pdfChoose a width that matches the layout you intend to print, then verify that media queries and horizontal overflow behave as expected. The viewport is not the same thing as PDF paper width: it controls layout before pagination, while page geometry controls the output sheet.
Rank #3
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
5. Check screen versus print CSS
The CLI defaults to screen media. --print-media-type switches to print media. Inspect every @media print rule for smaller font sizes, changed widths, hidden elements, transforms, or alternate spacing.
- Render once without
--print-media-type. - Render again with it.
- Compare computed layout in a browser and inspect the corresponding media block.
- Use the mode that matches your design; do not enable print media simply because the destination is a PDF.
wkhtmltopdf --page-size A4 input.html screen-media.pdf
wkhtmltopdf --page-size A4 --print-media-type input.html print-media.pdf6. Calibrate zoom and DPI only after geometry is correct
Zoom
The CLI documents --zoom with a default of 1. Use a changed value only after page size, margins, viewport, media mode, and shrinking have been checked. Record the value with the deployment configuration because it is an environment-specific calibration, not a CSS invariant.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallDPI
The documented DPI default is 96. The manual notes that DPI has no effect on X11-based systems. Therefore, a DPI adjustment that appears to help on one machine may do nothing on another. Treat DPI as a renderer/platform setting, not a replacement for fixing an over-wide layout.
wkhtmltopdf --page-size A4 --zoom 1 --dpi 96
--print-media-type input.html calibrated.pdfChange one of these values at a time and measure the fixture after every run.
7. A repeatable diagnostic workflow
- Record version, OS, patched-Qt status, wrapper, command, and fonts.
- Render the unchanged fixture with explicit paper size and margins.
- Compare default smart shrinking with
--disable-smart-shrinking. - Set a deliberate viewport if responsive CSS, overflow, or scrollbars matter.
- Compare screen and print media only when you know which output you want.
- Only now test zoom or DPI, measuring the known box each time.
- Run the winning command on the production host with the same binary and fixture.
- If the discrepancy remains, attach the version, OS details, command, and minimal HTML/CSS/JS reproducer to a support report.
Common failures and precise fixes
Everything is smaller, but nothing is clipped
Likely smart shrinking or a scale mismatch. Compare the default and no-shrink outputs, then inspect paper width and margins. Keep the setting that fits your required content without distorting measured dimensions.
Disabling smart shrinking makes the right edge disappear
Your layout exceeds the printable width. Restore shrinking or reduce the CSS width/margins and set the intended paper size. The documented issue on Windows Server 2012 R2 shows why “disable it” is not a universal answer.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsOnly print output is smaller
A print-media rule is changing dimensions. Compare both media modes and remove or revise the rule that changes width, font size, transform, or zoom.
Desktop and server PDFs differ
Check binary version, patched-Qt build, OS, installed fonts, locale, viewport, and every flag. Re-run the minimal fixture in both environments. Do not infer a universal Windows/Linux conversion factor from one historical report.
Changing DPI has no effect
If the host uses X11, the manual says DPI has no effect. Focus on page geometry, viewport, shrinking, and zoom instead.
Fonts or images alter apparent size
Missing fonts can change line wrapping and block heights, making a page appear scaled. Install the same fonts or use a controlled font stack in the fixture. Wait for assets and JavaScript explicitly in your wrapper before treating layout changes as scaling.
Best Value
Performance, reliability, and maintenance considerations
Keep the diagnostic fixture in source control beside the exact command and renderer version. Pin the deployment image or executable where possible, and compare generated PDFs in CI using measured page dimensions rather than screenshots alone. Repeatedly changing zoom to accommodate one host creates fragile output on another.
The wkhtmltopdf GitHub repository is archived and read-only as of January 2, 2023. That does not prove an immediate failure, but it is a maintenance risk for long-lived systems. When evaluating another renderer, compare CSS and print fidelity, repeatability across operating systems and deployment images, control over paper geometry and viewport, and the migration effort for existing HTML and JavaScript. The documented controls above are the baseline you should reproduce before switching.
Or skip the browser setup
If your goal is a clean capture rather than maintaining a wkhtmltopdf environment, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; each response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers. Its MCP tools—take_screenshot, get_page_info, and capture_pdf—work with Claude, Cursor, and other MCP clients.
One request returns an image or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the parameter reference and options in the ScreenshotNeo documentation. The service supports full-page capture with lazy images loaded, CSS-selector element capture, device presets or custom viewports, dark mode, retina scale, PDF paper and page-range controls, custom CSS and JavaScript, clicks, selector or network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, TTL caching, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work, easing migration.
Python:
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)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Frequently Asked Questions
Does wkhtmltopdf use CSS pixels as physical PDF points?
Not consistently. Smart shrinking, DPI, zoom, page geometry, and platform behavior can make the pixel-to-DPI relationship non-constant.
Should I always pass –disable-smart-shrinking?
No. Use it as a comparison. On some environments it restores apparent scale; on others it causes overflow and clipping.
Why can the same A4 command differ between Linux and Windows?
Renderer builds, patched-Qt behavior, fonts, operating-system details, and defaults can differ. Reproduce with the same binary and a minimal fixture.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
