The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →When CSS is missing or looks different in a wkhtmltopdf PDF, first verify that the exact stylesheet and its dependent assets load, then check screen-versus-print media, JavaScript readiness, and page geometry. wkhtmltopdf 0.12.6 uses a patched Qt renderer, so a browser preview is not a reliable substitute for testing the exact binary that generates your PDFs. The steps below isolate those causes without changing several variables at once.
How wkhtmltopdf applies stylesheets
wkhtmltopdf converts HTML pages to PDF using a patched Qt build. Its 0.12.6 manual documents controls for a user stylesheet, screen or print media, local-file access, JavaScript diagnostics, media-load errors, viewport size, and smart shrinking. These options let you investigate whether CSS was found, which rules are active, when the page is ready, and how it is laid out on the PDF page; they do not guarantee compatibility with every modern browser feature. See the wkhtmltopdf usage manual and library settings reference.
There is important legacy-engine context: the project status page says Qt 4 had been unsupported since 2015 and the WebKit version in it had not been updated since 2012. The 0.12.6 release is dated June 11, 2020, and the GitHub repository became read-only on January 2, 2023. Those dates are reasons to test your deployed binary carefully, not a complete CSS compatibility table. The official sources do not establish that a particular CSS feature will always fail; behavior can depend on the build. See project status, the release page, and the changelog.
Start by identifying the renderer and reproducing the problem
- Record the binary and environment. Run
wkhtmltopdf --version. Save the complete output, operating system and version, and whether the output identifies patched Qt. Different distribution packages and standalone builds can behave differently even when their broad version label matches. - Reduce the page to a fixture. Keep one HTML file, the CSS relevant to the failure, and only the assets needed to observe it. Compare the fixture in a normal browser and in the PDF. Keep the same inputs and command line as you investigate.
- Change one variable at a time. Test resource access, media selection, JavaScript timing, and geometry independently. If you alter several options together, a changed result will not tell you which one mattered.
This also prepares a useful issue report. The project asks for the version, operating system and version, a detailed description, and a reproducing HTML/CSS/JS example. Its support page says: “A detailed description of the issue, along with a test case (with HTML/CSS/JS) to duplicate the issue, so that we can look into it”. See Reporting Issues – wkhtmltopdf.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Why is my CSS not loading in wkhtmltopdf?
Check the stylesheet URL and base path
Inspect the HTML href and establish what URL or directory the converter uses as the base for relative paths. Check filename capitalization, since paths that work on a case-insensitive development system may not match files on another system. Confirm that the conversion process—not just your desktop browser—can reach the stylesheet and that permissions allow it to read the file.
Check local-file access for local HTML
The documented 0.12.6 manual says local-file reads are disabled by default unless explicitly allowed. The --allow option grants access to specified local paths; --enable-local-file-access permits reads from other local files. Prefer granting access only to the directories the conversion needs. This matters especially if HTML or paths can be influenced by untrusted input.
For diagnosis, test a narrowly scoped --allow path first. If your page uses other local files and you deliberately need broader access, the manual documents this command-line option:
wkhtmltopdf --enable-local-file-access input.html output.pdf
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 reinstallOutdated 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 matchThat example enables local-file access; it does not fix a wrong path, missing file, or restrictive filesystem permission. Consult the usage manual for the access options supported by the documented version.
Test a user stylesheet
If you need to distinguish a stylesheet-link problem from a broader styling issue, try a small user stylesheet containing one obvious rule. Qt WebKit documents user stylesheets as either a local path or a UTF-8 base64 data URL; malformed base64 will prevent the style from applying. Keep the test rule simple, then remove it once you know whether the mechanism works. A user stylesheet is a diagnostic route, not proof that the page’s linked CSS or all its rules are loading correctly.
Why does the PDF look different from the browser?
Compare screen and print media
In the documented 0.12.6 manual, screen media is the default. The --print-media-type switch selects print media. If the missing rule is inside @media print, compare the default output with a print-media run:
wkhtmltopdf --print-media-type input.html output-print.pdf
Recommended Free Tools
Inspect the fixture for print-specific hiding, colors, margins, and page-break declarations. A rule can be working as written while being inactive in the selected media mode. Do not assume screen and print rules should produce identical output.
Hold viewport and shrinking steady
A rule may apply but appear wrong because the page is laid out at a different size or scaled to fit. Record and test the viewport, page size, DPI, margins, and smart-shrinking setting. The documented --viewport-size option controls the emulated window size; --disable-smart-shrinking turns off the documented WebKit shrinking strategy. Try each adjustment separately when text wraps unexpectedly, elements look scaled, or content overflows.
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
For example, to test a particular viewport without changing media selection at the same time:
wkhtmltopdf --viewport-size 1280x1024 input.html output.pdf
Use the dimensions appropriate to your page rather than treating that example as a universal setting. Check the manual for your installed build’s supported syntax and the effects of page size, DPI, and margins.
Separate styling from pagination
First determine whether the desired rule takes effect on a single-page or otherwise small fixture. Only then investigate page breaks, repeated headers or footers, and margins. Pagination can make a correctly styled element appear misplaced or split; changing CSS before distinguishing layout from page-boundary effects can obscure the actual cause.
Why are fonts, images, or imported styles missing?
A linked stylesheet can load while a font, image, or CSS import fails. Check every dependency from the converter’s environment: its URL or local path, case, permissions, and reachability. A browser may have cached a resource or be able to access a local file that the PDF process cannot.
The manual’s default media error behavior is ignore, so a successful PDF exit does not prove all media loaded. During diagnosis, inspect stderr and use the documented --load-media-error-handling option to choose how media-load failures are handled. The library reference also exposes load-error and media-error controls. Treat warnings and missing assets as separate evidence from the process exit status; choose stricter handling when you need failures to be visible rather than silently ignored.
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 problemsIf backgrounds are absent, inspect --background and --no-background. The manual documents backgrounds as printed by default, while --no-background disables them. Check whether the option is being supplied explicitly before rewriting background CSS.
How do I debug JavaScript-created styles or content?
If JavaScript adds markup or changes styles after the initial page load, first confirm that JavaScript is enabled and that the relevant code runs in the converter. Use --debug-javascript to expose warnings and errors. The manual documents a default JavaScript delay of 200 ms, along with --javascript-delay and --window-status for controlling when conversion proceeds.
A delay can help determine whether the PDF is being captured before a page finishes its work, but it is a diagnostic or targeted workaround—not a general CSS fix. Prefer a readiness signal where the page can set one reliably. If the style still fails after the generated content is present, continue by checking media selection, resource loading, and the exact renderer.
Diagnosis map for common CSS symptoms
| Symptom | First checks | Next useful test |
|---|---|---|
| No styling at all | Stylesheet URL/base path, file access, permissions, and media-load warnings | Apply a minimal user stylesheet to distinguish stylesheet-link failure from broader rendering behavior |
| Some rules work and others do not | Whether the declarations are under screen or print media | Reduce the failing selector and property to a one-rule fixture, then test the exact installed build |
| Browser looks right but PDF does not | Binary version and patched-Qt status, media mode, viewport, shrinking, page dimensions, and font/image loading | Change one setting at a time while retaining the same HTML and assets |
| Styles look stale or inconsistent | Actual served stylesheet contents, URL, cache layer, and whether the converter can retrieve the latest file | Save a deterministic local fixture and verify the exact CSS it references |
| PDF succeeds but assets are missing | Warnings and the default media-error behavior | Use documented media-load error handling to make failures easier to detect |
The official documentation reviewed does not provide a comprehensive current CSS compatibility matrix or empirical CSS success rates. For a property or selector that appears unsupported, verify it against the exact deployed binary using a minimal case rather than generalizing from another package or from the age of the engine.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
Make the result repeatable before changing production CSS
- Keep the minimal HTML, CSS, and required assets together, with the command line used to generate the PDF.
- Record the renderer version, patched-Qt indication, operating system and version, media mode, viewport, page dimensions, DPI, margins, and shrinking setting.
- Capture stderr and note missing-resource warnings, JavaScript messages, and the output file’s visible differences.
- Re-run the unchanged fixture after each single-option change. This distinguishes a reproducible engine or configuration issue from changing source files or asset availability.
- When reporting an issue, provide the environment details and reproduction material requested by the project’s reporting guidance.
Or skip the browser setup
If your actual need is a clean screenshot rather than a wkhtmltopdf-specific PDF, ScreenshotNeo is a website screenshot API and MCP server. A single GET request can return PNG, JPEG, WebP, or PDF. Its cookie and consent handling accepts banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients.
For a quick PDF capture, use the same endpoint with a URL and PDF output option supported by the ScreenshotNeo API documentation. For example, this runnable cURL request saves a WebP screenshot:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
Replace YOUR_API_KEY with your key and change the target URL. ScreenshotNeo also supports full-page capture, CSS-selector element capture, dark mode, device and custom viewport settings, retina scale, PDF page settings, HTML/CSS-to-image, custom CSS and JavaScript, pre-capture clicks, selector hiding, wait conditions, request/resource blocking, custom headers and cookies, user agent and Authorization, timezone and geolocation, transparent backgrounds, resizing, configurable-TTL caching, signed image links, asynchronous jobs with signed webhooks, bulk capture up to 100 URLs per call, a usage API, and an OpenAPI spec. Other screenshot APIs’ parameter names also work to ease switching.
Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed; an MCP server lets AI agents take screenshots; and 1,000 screenshots a month are free with no card, with paid plans starting at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does wkhtmltopdf 0.12.6 use print CSS by default?
No. The documented default is screen media; use --print-media-type to select print media.
Does a successful wkhtmltopdf exit mean every stylesheet asset loaded?
No. The documented default for media-load errors is ignore, so inspect warnings and test resource handling when assets are missing.
Is there an official current CSS compatibility list for wkhtmltopdf?
The official sources cited here do not provide a comprehensive current CSS compatibility matrix. Test a minimal reproduction with the exact binary you deploy.
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.
