Use --disable-smart-shrinking only when you need a predictable pixel-to-DPI scale. It turns off WebKit’s automatic shrinking; it does not make an oversized document fit. If your HTML is wider or taller than the PDF page, disabling shrinking can produce clipping or overflow. First verify the exact wkhtmltopdf binary and whether it is a patched-Qt build, then test the flag with a minimal file and adjust page geometry deliberately.
What --disable-smart-shrinking actually changes
The wkhtmltopdf 0.12.6 usage manual describes smart shrinking as WebKit’s strategy for making the pixel-to-DPI ratio non-constant. Smart shrinking is enabled by default. With --disable-smart-shrinking, WebKit no longer reduces the rendered scale automatically when content is too wide for the selected page.
That is useful when CSS dimensions, screenshots, or print layouts must retain a stable scale. It is not a general fix for bad wrapping, missing fonts, incorrect margins, or content that simply does not fit. The trade-off is direct:
- Enabled (default): more of a wide layout may fit, but the effective scale can change between documents.
- Disabled: scale is more predictable, but content can run beyond the right or bottom edge and be clipped or paginated unexpectedly.
The command-line switch is --disable-smart-shrinking. In the library interface, use web.enableIntelligentShrinking=false on the relevant page object.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
Check the binary before changing your HTML
Behavior depends on the exact version, operating system, package, and Qt build. Some wkhtmltopdf packages are built without the project’s Qt patches; those builds can lack functionality or behave differently from the documented binaries.
- Run
wkhtmltopdf --version. - Record the complete output, including any indication that the binary uses patched Qt.
- Record the operating system, installation source, page size, orientation, margins, zoom or DPI settings, and whether the symptom is scaling, clipping, or pagination.
- If the option is reported as unknown or appears to do nothing, compare the binary’s build characteristics with the project’s documented download and package information before editing CSS.
Do not assume that two executables both labeled 0.12.6 render identically. A distribution package and an official patched-Qt build can produce different results.
Reproduce the problem with a minimal file
Reduce the document to a representative width, a long section, and the CSS that controls the failing region. This separates wkhtmltopdf geometry from JavaScript, fonts, network requests, and application code.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
@page { size: A4; margin: 18mm; }
* { box-sizing: border-box; }
body { margin: 0; font: 14px/1.45 Arial, sans-serif; }
.sheet { width: 170mm; }
.wide-table { width: 100%; border-collapse: collapse; }
th, td { border: 1px solid #999; padding: 4px; }
</style>
</head>
<body>
<main class="sheet">
<h1>Scale test</h1>
<table class="wide-table">
<tr><th>Column A</th><th>Column B</th><th>Column C</th></tr>
<tr><td>Representative text</td><td>1234567890</td><td>End marker</td></tr>
</table>
</main>
</body>
</html>Save it as scale-test.html. Run a baseline with the default behavior:
Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
wkhtmltopdf scale-test.html baseline.pdfThen run the same file with shrinking disabled:
wkhtmltopdf --disable-smart-shrinking scale-test.html no-shrink.pdfCompare the right edge, bottom edge, text size, line breaks, and page count. Keep the command output and binary version beside the PDFs so a later package upgrade can be diagnosed rather than guessed.
Make the page fit without hiding the real cause
Set the physical page first
Choose the intended paper size and orientation explicitly, for example --page-size A4 or --page-size Letter, and use --orientation Portrait or --orientation Landscape. A layout designed for landscape will often clip in portrait when shrinking is disabled.
Account for margins
The usable width is the paper width minus the left and right margins. Set all four margins when reproducing a bug:
wkhtmltopdf
--page-size A4
--orientation Portrait
--margin-top 18mm
--margin-right 18mm
--margin-bottom 18mm
--margin-left 18mm
--disable-smart-shrinking
scale-test.html output.pdfThen make the main container no wider than the resulting content area. Prefer physical units for print geometry and avoid a fixed pixel width that exceeds the page.
Recommended Free Tools
Rank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
Use zoom or DPI only as a tested adjustment
Options such as --zoom and --dpi alter the rendered scale, but no universal value is established for this problem. Suggestions found in issue discussions are tied to particular versions, operating systems, page sizes, and builds. Treat a value as a hypothesis: change one setting, regenerate the PDF, and inspect both edges and pagination.
Fix overflow in CSS
- Replace fixed widths larger than the printable area with responsive widths such as
width:100%. - Use
overflow-wrap:anywherefor long identifiers and URLs. - Check tables, absolutely positioned elements, transforms, and negative margins; these commonly extend beyond the containing block.
- Load the fonts available to the conversion process and verify that fallback fonts are not changing line lengths.
- For intentionally wide content, choose landscape orientation or accept multiple pages instead of forcing a scale that makes text unreadable.
A repeatable diagnostic procedure
- Capture the environment: version output, patched-Qt indication, OS, input URL or file, and all rendering flags.
- Establish a baseline: render without the flag and save the PDF.
- Toggle one variable: render with
--disable-smart-shrinkingwhile keeping every other option unchanged. - Inspect boundaries: check the final column, rightmost graphic, footer, and bottom-most content at 100% PDF zoom.
- Adjust geometry: change page size, orientation, margins, or CSS dimensions before experimenting with zoom or DPI.
- Validate pagination: a visually acceptable first page can still have a clipped footer or an unexpected extra page.
- Retest on the deployment binary: local results do not prove that a different package or operating system will match.
Library and wrapper configuration
When using a language binding rather than the executable, the equivalent setting is web.enableIntelligentShrinking=false. Set it on the page object that produces the PDF, not merely on an unrelated global or document object. Confirm that your wrapper passes the setting through to wkhtmltopdf and that the underlying binary supports it.
A useful wrapper-level checklist is:
- Log the resolved executable path and
--versionoutput. - Log page size, orientation, margins, zoom, and DPI alongside the HTML revision.
- Fail loudly when the wrapper rejects the setting instead of silently falling back to defaults.
- Keep a small fixture PDF in automated tests and compare dimensions, page count, and boundary markers after upgrades.
Troubleshooting common symptoms
| Symptom | Likely cause | Action |
|---|---|---|
| “Unknown long argument” | The executable or package does not expose the option. | Check wkhtmltopdf --version, identify the build, and compare it with a documented patched-Qt package. Do not compensate by randomly changing CSS. |
| No visible change after adding the flag | The page already fits, the wrapper dropped the setting, or the build handles it differently. | Use the minimal fixture, inspect wrapper logs, and compare baseline and no-shrink PDFs at the same scale. |
| Right side is cut off | Content width exceeds the printable width once automatic shrinking is removed. | Reduce CSS width, lower margins, switch to landscape, choose a larger page, or test a documented zoom adjustment. |
| Bottom content is missing | Fixed-height containers, absolute positioning, or page-break behavior extends below the page. | Remove restrictive heights, inspect positioned elements, and test pagination with a longer fixture. |
| Text wraps differently after an upgrade | Different Qt patches, fonts, DPI, or package defaults. | Pin the executable and fonts, record environment details, and rerun the fixture on the target host. |
| Output varies by operating system | Historical issue reports show environment-specific rendering differences. | Compare exact binaries and settings; do not promote a workaround from one host to a universal rule. |
What this option cannot do
--disable-smart-shrinking does not sanitize HTML, remove scripts, fix broken network requests, or make untrusted input safe. The project’s download guidance warns that untrusted HTML must be sanitized because user-supplied HTML and JavaScript can compromise the server running the converter. Run conversion in an appropriately isolated environment and sanitize input before rendering.
It also cannot guarantee identical physical output across builds. The documented meaning of the switch is stable, but issue discussions demonstrate that scale and clipping outcomes depend on version, OS, page geometry, and package build.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Rank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
Or skip the browser setup
If your actual goal is a clean image or PDF of a web page rather than control of a local WebKit binary, ScreenshotNeo provides a single HTTP request. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients.
See the ScreenshotNeo documentation for authentication and options. A direct call looks like this:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));Every feature is included on every plan. The Free plan provides 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account to try it.
Frequently Asked Questions
Does disabling smart shrinking change the HTML or CSS itself?
No. It changes WebKit’s rendering-scale behavior during conversion; your source files remain unchanged.
Should I enable the option in production by default?
Only if your tested page geometry requires a stable scale. Keep a fixture and validate page count and edge clipping whenever the binary, fonts, OS, or CSS changes.
Can a patched-Qt build still produce clipping with the flag?
Yes. Patched Qt affects feature support and behavior, but disabling shrinking does not make content narrower than the printable page.
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.
