To control CSS layout in wkhtmltopdf, first make sure it is using the intended stylesheet rules, then set the PDF page geometry and renderer options deliberately. Use --print-media-type when your layout depends on @media print, and test intelligent shrinking if content appears unexpectedly small. wkhtmltopdf uses Qt WebKit rather than a current mainstream browser engine, so verify the exact CSS behavior against the binary and operating system that will generate your PDFs.
How wkhtmltopdf decides which CSS layout to render
wkhtmltopdf converts HTML into PDF using Qt WebKit. Its output depends on more than the CSS in the page: the renderer build, media mode, page dimensions, margins, zoom, viewport, background setting, and shrinking behavior can all affect what ends up on the PDF canvas. The project’s overview describes the tool at wkhtmltopdf.org; its status page explains the age of the rendering engine.
This distinction matters when debugging display. A browser preview and a PDF can differ because they selected different media rules, because the page was scaled to fit, or because the WebKit build handles a CSS feature differently. First check configuration and page composition; only then conclude that a particular CSS declaration is unsupported.
Make print and screen rules explicit
Use print media when the PDF needs print CSS
If the desired rules are inside @media print, enable print-media rendering with the command-line option --print-media-type. The corresponding library setting is load.printMediaType. Without that switch, the renderer may use screen media, so a print-only display rule may not be selected. The official settings reference documents the print-media setting and related controls.
@media print {
.screen-only { display: none; }
.report-layout { display: block; }
}Use the print option only when print rules are intended. If the page is designed with screen styles and those styles should drive the PDF, compare output with print media disabled rather than adding print rules blindly.
Inject a focused override with a user stylesheet
When you cannot edit the source HTML, a user stylesheet can apply targeted CSS during conversion. The library setting is web.userStyleSheet; command-line builds commonly expose this as --user-style-sheet. Use a small override so you can tell which rule changed the result.
/* pdf-overrides.css */
@media print {
.navigation, .chat-widget { display: none !important; }
.report { display: block !important; }
}For example, run wkhtmltopdf --print-media-type --user-style-sheet /absolute/path/pdf-overrides.css input.html output.pdf. Confirm option availability and spelling with the help output for the exact installed binary, especially when using a vendor or distribution build.
Check background rendering separately
Background colors and images can disappear even when the layout is otherwise correct. The settings include a background-printing control; check whether background printing is enabled for the intended output. A missing background is not evidence that a display rule failed.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Set the PDF canvas before adjusting CSS
Page size, orientation, margins, viewport, and zoom determine the space in which CSS is composed. Establish these inputs before tweaking widths or font sizes. Otherwise, a stylesheet tuned for one page geometry can appear broken when rendered with another.
- Page size or dimensions: choose the intended paper size or explicit page dimensions. A narrow page can cause wrapping or overflow that a wider page does not.
- Orientation: landscape gives a wider canvas than portrait, changing line breaks and the available width for columns.
- Margins: margins reduce the usable content area. If a layout is nearly page-wide, even modest margins can force wrapping or scaling.
- Viewport and zoom: these influence the page’s rendered dimensions and apparent scale. Record them when reproducing an issue.
- Intelligent shrinking:
web.enableIntelligentShrinkingcan shrink content to fit more onto a page. Compare output with shrinking enabled and disabled when elements look too small or compressed. Do not assume shrinking fixes overflow without affecting scale.
The complete list and library names are in the official settings reference. Command-line option availability can vary by build, so use wkhtmltopdf --help on the machine producing the PDF rather than copying an unverified flag from a different installation.
A repeatable workflow for a layout problem
- Record the renderer: run
wkhtmltopdf --versionand note the operating system and version, package or build source, and relevant installed fonts. - Fix the PDF geometry: set page size, orientation, margins, viewport, and zoom deliberately. Keep those settings unchanged while diagnosing CSS.
- Choose the media mode: enable
--print-media-typeif the expected declarations are under@media print; otherwise compare against screen media. - Inspect scaling and backgrounds: compare intelligent shrinking on and off, and verify background printing independently of the element layout.
- Reduce the page: create a minimal HTML/CSS/JavaScript example that retains the failing element and its relevant parents, styles, and assets.
- Render with the deployment binary: inspect the PDF itself, not just a browser preview, and reproduce using the same OS, build, fonts, and options as production.
- Change one variable at a time: test a media switch, page setting, or CSS override individually so the cause remains identifiable.
The project’s downloads page notes that Qt choices, system libraries, and runtime font configuration can produce behavioral differences. Its support guidance asks for the wkhtmltopdf version, OS and version, and a reproducible HTML/CSS/JavaScript case. Providing those details makes a layout problem substantially easier to reproduce.
What to expect from CSS display values
The official settings reference documents renderer controls, not a comprehensive CSS conformance matrix. The reviewed project documentation does not establish a universal support guarantee for specific display values, including flexbox or grid, across wkhtmltopdf builds. Avoid relying on a general claim that a modern layout value will behave identically in every PDF deployment.
If a layout depends on a particular display mode, build the smallest page that demonstrates it and test that page with the exact binary used in production. If an equivalent simpler layout meets the need, testing a less complex arrangement can isolate whether the problem is the CSS feature or the renderer configuration; it is not a guarantee that the simpler rule will fix every build.
Engine age is a material constraint. The maintainer’s status page says Qt 4 support ended in 2015 and that its WebKit had not been updated since 2012. Those are project status statements, not a property-by-property compatibility test, but they are a reason to validate rather than assume support for newer browser behavior.
Troubleshoot the symptoms you see in the PDF
| Symptom | Likely check | Next step |
|---|---|---|
A print-only display rule seems ignored |
Print media may not be selected. | Render with --print-media-type and compare against the intended @media print rules. |
| Everything appears smaller than expected | Intelligent shrinking, page width, margins, zoom, or viewport may be changing scale. | Hold page settings fixed and compare output with intelligent shrinking enabled and disabled. |
| Columns wrap or overflow | The usable page width may be smaller than the CSS layout expects. | Check page size, orientation, margins, viewport, and any width constraints before rewriting display rules. |
| Background color or image is absent | Background printing may be disabled. | Check the background setting separately from the CSS layout. |
| Layout differs between machines | Build, Qt choices, system libraries, OS, or fonts may differ. | Record version and platform details and reproduce on the deployment binary. |
| A modern layout behaves inconsistently | The exact feature may not be established for that build. | Reduce to a focused test case and validate the required display behavior directly. |
When to retain wkhtmltopdf and when to consider another renderer
Keeping wkhtmltopdf can be reasonable when the existing output is stable, the deployment environment is controlled, and the CSS and JavaScript behavior your documents need has been verified on that build. A migration deserves consideration when the layout depends on browser features the current output cannot render reliably, when dynamic JavaScript is central, or when maintaining the legacy runtime is an operational problem.
The maintainer’s status page points readers toward Puppeteer for dynamic JavaScript and mentions WeasyPrint or Prince as alternatives for controlled report generation. These are maintainer suggestions, not comparative benchmark results or a guarantee that any alternative will match an existing PDF. Before switching, compare required CSS fidelity, JavaScript needs, target-OS runtime compatibility, handling of user-supplied HTML, and the stability of output during migration.
Windows 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 reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteProtect the host when rendering HTML
Do not pass untrusted HTML or JavaScript to wkhtmltopdf without appropriate sanitization and isolation. The project explicitly warns that malicious user-supplied content can put the server running the renderer at serious risk. Sanitization is important, but it should not be the only boundary: the project’s AppArmor guidance explains that local-file-access restrictions alone may not contain an exploit in a prebuilt binary and recommends mandatory access controls such as AppArmor or SELinux as an additional safeguard.
- Restrict which content and scripts the renderer can process; do not assume a URL or uploaded document is safe.
- Run the conversion process with limited permissions and an appropriate isolation boundary.
- Apply the relevant platform controls, such as AppArmor or SELinux, according to your deployment environment.
- Keep the renderer away from credentials and files it does not need to access.
Or skip the browser setup
If your requirement is to capture a rendered web page rather than debug wkhtmltopdf’s CSS behavior, ScreenshotNeo offers a one-request screenshot API and PDF output. This is a different workflow from configuring a wkhtmltopdf binary; use it when an API capture fits the job.
For a screenshot, one GET request returns an image. The response can be PNG, JPEG, or WebP; ScreenshotNeo also supports PDF capture. See the ScreenshotNeo API documentation for API parameters and output options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response indicates the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsSign up for 1,000 free screenshots a month with no card.
Best Value
Frequently Asked Questions
Which wkhtmltopdf option selects CSS inside @media print?
Use --print-media-type in command-line usage; the corresponding library setting is load.printMediaType.
Does the official documentation guarantee flexbox or grid support?
No property-by-property guarantee is established in the official settings reference. Test the exact layout on the binary and platform that will generate the PDF.
Can ScreenshotNeo replace wkhtmltopdf for every HTML-to-PDF workflow?
Not necessarily. ScreenshotNeo provides screenshot and PDF capture, while this article’s wkhtmltopdf guidance concerns configuring its renderer; check the ScreenshotNeo documentation to confirm its capture options match your requirements.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
