Short answer: wkhtmltopdf handles traditional HTML and CSS reliably enough for document-style pages, but it is not a modern browser. Its Qt WebKit engine predates current flexbox, Grid, JavaScript and responsive-CSS expectations. Normal block and inline flow, the box model, floats, tables, positioning, typography, colors, borders, backgrounds and many print page-break rules are the safest baseline. Treat display:flex, CSS Grid and newer browser APIs as unsupported unless your exact binary proves otherwise.
The engine determines the CSS ceiling
wkhtmltopdf renders HTML to PDF (and wkhtmltoimage renders images) through Qt WebKit. That distinction matters more than the CSS file itself: declarations are interpreted by the WebKit version embedded in the executable, not by the browser installed on your computer.
The project’s status page says that Qt 4, which wkhtmltopdf uses, has not been supported since 2015 and that its embedded WebKit has not been updated since 2012. The official downloads page lists the 0.12.6 series as stable, released on June 11, 2020. The GitHub repository was archived on January 2, 2023. Consequently, a PDF can be generated successfully while silently ignoring layout declarations that a current Chrome or Firefox accepts.
There is no official, exhaustive property-by-property compatibility matrix. Support can also differ between patched-Qt and unpatched-Qt builds, operating systems, fonts and command-line options. The practical answer is therefore a tested baseline, not a claim that wkhtmltopdf supports “CSS3” as a whole.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
CSS that is generally safe
These features match the older-browser model in which wkhtmltopdf was designed. They still need visual testing for complex documents, but they are sensible starting points.
| Area | Usually workable features | Implementation advice |
|---|---|---|
| Document flow | Block and inline elements, normal flow, width and height, margins, padding, borders and box-sizing patterns supported by old WebKit |
Build the page as a document first. Avoid relying on automatic sizing behavior introduced by newer layout specifications. |
| Layout | Floats, clear, tables, fixed positioning and absolute positioning |
Use explicit widths and clearfixes. Tables are often the most predictable way to align columns in reports. |
| Appearance | Solid colors, borders, background colors and many background images | Keep a solid-color fallback before any visual effect that may vary by build. |
| Typography | Common font families, font size, weight, style, line height, alignment, wrapping and decoration | Install required fonts on the rendering host and test glyph coverage. A browser’s locally installed fonts are not automatically available on a server. |
| Print-oriented CSS | Page size and margins through command-line options, plus older page-break properties such as page-break-before, page-break-after and page-break-inside |
Check real page boundaries. A rule can be recognized yet still be defeated by an oversized table row or replaced element. |
| Selectors | Element, class, ID, attribute and ordinary descendant/child selectors | Prefer simple selectors when the document is business-critical; complicated selector behavior is more likely to expose old-WebKit differences. |
“Generally workable” does not mean identical to a current browser. Test nested floats, long unbroken strings, large tables, images and repeated headers with the production executable.
Flexbox: do not make it your baseline
Modern flexbox is unreliable in wkhtmltopdf. A project forum answer states that version 0.12.4 “doesn’t support flexbox.” A separate issue reports flexbox failures in 0.12.6 even with a patched Qt build and prefixed declarations. In practice, a declaration such as display:flex may be ignored, may fall back to block layout, or may produce a partially correct result.
If you must support an existing flex-based template:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Provide a non-flex fallback earlier in the cascade, such as floats or a table layout.
- Give columns explicit widths instead of depending on flex growth and shrink calculations.
- Do not assume
flex-wrap, ordering, alignment, or automatic height distribution will work. - Render representative pages with the exact 0.12.x binary used in production; a prefixed declaration is not proof of support.
For a new template, start with floats, tables or a modern browser renderer rather than designing in flexbox and attempting to retrofit it later.
CSS Grid and newer layout APIs
CSS Grid should be treated as unsupported. The embedded WebKit predates the standardized Grid implementations used by current browsers. The same caution applies to newer layout and platform APIs whose behavior depends on a modern browser engine. If a Grid declaration is ignored, children usually return to normal flow, which can look like a mysterious “missing” column rather than an explicit error.
Responsive frameworks amplify this problem. Bootstrap versions that depend on flexbox, and Tailwind utilities that emit flex, Grid, modern selectors or newer functions, can render as stacked blocks or lose alignment. You can either:
- Compile a dedicated print stylesheet that replaces modern utilities with fixed widths, floats and table-like structures.
- Use a browser engine with current CSS support for that template.
- Keep a small legacy HTML template specifically for PDF generation.
A viewport meta tag does not upgrade wkhtmltopdf. Media-query behavior and viewport dimensions must be tested with your chosen command-line width and zoom settings.
Features that need fallbacks and testing
Older WebKit has partial or build-sensitive behavior for several features that are common in contemporary stylesheets:
- Gradients and transforms: retain a flat-color or untransformed fallback. Vendor-prefixed syntax may be required by some builds, but prefixes do not guarantee identical output.
- Animations and transitions: they are poor choices for a static PDF. Capture timing can leave an element at an unexpected state.
calc()and newer CSS functions: verify every calculated width and margin. Replace critical calculations with server-generated pixel values when possible.- Pseudo-elements:
::beforeand::aftercan work for simple generated content, but test counters, replaced elements and page breaks. - SVG and web fonts: test local and remote assets, font loading time and fallback glyphs. A missing font or blocked resource changes line wrapping and therefore pagination.
- Media queries: use them for conservative print adjustments, not as a substitute for a modern responsive engine. Confirm which media mode and viewport your invocation uses.
Unsupported declarations are normally ignored rather than reported. Always inspect the resulting pages, not just the process exit code.
JavaScript and page readiness
wkhtmltopdf exposes --run-script and --window-status, so it can execute some scripts and wait for a page to report a status. Its JavaScript runtime is nevertheless old, and modern client applications may fail before CSS is even evaluated. The project’s own guidance recommends Puppeteer or another modern wrapper for dynamic JavaScript pages.
For a static or server-rendered document, disable unnecessary scripts and make all required data present in the initial HTML. For a dynamic page, you need a deterministic readiness signal and a timeout strategy:
Free tools Windows power users keep installed
One-click scans. No signup required.
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
wkhtmltopdf --javascript-delay 1500 input.html output.pdf
# Or wait for page JavaScript to set: window.status = 'ready'
wkhtmltopdf --window-status ready input.html output.pdfDo not use a delay as a guarantee that network requests, fonts and images have finished. It is only a fixed wait. A status signal is more deterministic when you control the page.
Build differences, assets and security checks
Two machines can produce different PDFs from the same HTML. Record the binary version, operating system, patched-Qt status, installed fonts and command-line flags alongside your source. Some options in the usage documentation require patched Qt; an option accepted by one package may be unavailable or behave differently in another.
- Local files: local images, stylesheets and fonts may require
--enable-local-file-access. Only enable it when the input is trusted. - Remote files: verify DNS, TLS, authentication and response content from the rendering host. A browser window on your workstation succeeding does not prove the server can fetch the same URL.
- Cross-origin resources: old WebKit and server headers can block fonts, images or API calls. Prefer packaging critical assets locally.
- Untrusted HTML: treat JavaScript, file access and remote requests as attack surfaces. Isolate the process and restrict its network access in production.
A repeatable CSS compatibility test
Instead of guessing, create a small fixture containing one example of every feature your application uses. Include normal flow, a float layout, a table, a page break, a pseudo-element, your fonts, a gradient, a transform, a media query, flexbox and Grid. Keep the fixture in version control.
- Run
wkhtmltopdf --versionand record the complete output. - Render the fixture with the same flags, fonts, container image and input method used in production.
- Compare the PDF visually and, where possible, extract text or inspect page counts in automated checks.
- Change one variable at a time: binary, patched-Qt package, font, viewport, network access or CSS fallback.
- Retain the fixture as a regression test whenever you upgrade the executable or alter the stylesheet.
wkhtmltopdf --enable-local-file-access
--page-size A4
--margin-top 18mm --margin-right 15mm
--margin-bottom 18mm --margin-left 15mm
css-fixture.html css-fixture.pdfThis process tells you what your build supports, including interactions that a generic compatibility list cannot predict.
Crashes, 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 minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Troubleshooting common failures
Columns stack vertically
Likely cause: flexbox or Grid declarations were ignored. Fix: inspect the computed fallback, add explicit widths with floats or a table, and remove reliance on flex growth, wrapping or Grid tracks.
Styles appear to be missing
Likely cause: the stylesheet or font was not loaded, a selector is too modern for the embedded WebKit, or a local file was blocked. Fix: use absolute or packaged asset paths, check network responses from the renderer, enable local access only for trusted input, and simplify the selector.
Text wraps differently or pages overflow
Likely cause: a different font, missing glyphs, a changed viewport, or unsupported sizing such as a complex calc(). Fix: install and declare the exact fonts, set explicit widths and line heights, and test long strings and localized text.
Page-break rules seem ignored
Likely cause: the element is inside a table or cannot be split as requested, or the rule is a newer alias not understood by the build. Fix: test older page-break-* properties, move the break to a block-level wrapper, and avoid rows taller than a page.
JavaScript content is blank
Likely cause: the old runtime cannot execute the application, resources are blocked, or capture occurs before rendering completes. Fix: server-render the content, use a controlled --window-status signal, or move to Puppeteer/another current browser renderer.
When to replace wkhtmltopdf
| Requirement | Practical choice | Why |
|---|---|---|
| Legacy HTML, fixed report layouts and a small deployment footprint | wkhtmltopdf, with a tested fallback stylesheet | Traditional CSS and print-oriented documents can remain predictable when the binary and assets are controlled. |
| Modern CSS, flexbox/Grid or complex client-side applications | Headless Chrome through Puppeteer or another current browser wrapper | A current Chromium engine is a better match for modern layout and JavaScript. The wkhtmltopdf project recommends Puppeteer for dynamic pages. |
| Controlled, print-focused reports without browser JavaScript | WeasyPrint or Prince | The project status lists these as alternatives for controlled reports; evaluate their CSS and licensing requirements against your document. |
| Qt-based application needing a newer browser engine | Qt WebEngine | Qt WebEngine is Chromium-based and represents the more current engine architecture. |
Switch when the cost of legacy fallbacks, pagination defects or JavaScript workarounds exceeds the operational cost of a different renderer. Do not switch solely because a declaration is unfamiliar; first verify it in your production fixture.
Or skip the browser setup
If your goal is a clean screenshot or PDF of a web page rather than maintaining a wkhtmltopdf CSS pipeline, ScreenshotNeo is the first hosted screenshot API to try: it removes common consent banners, newsletter popups and chat widgets before capture, and only clean shots are billed.
One GET request returns PNG, JPEG, WebP or PDF. The API also supports full-page capture with lazy images, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF paper and margin controls, custom CSS and JavaScript, click and wait actions, blocked ads/trackers/resource types, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, a usage API and an OpenAPI specification. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.
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 →Failed loads, bot checks or CAPTCHAs, blank pages, timeouts and cache hits are not billed, and each response identifies the page verdict and billing result in X-Page-Verdict and X-Billed headers.
Best Value
See the ScreenshotNeo API documentation for parameters. The following call captures a page as WebP:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpEquivalent 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)Equivalent 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; every feature is available on every plan, and annual billing provides two months free. Create a free ScreenshotNeo account to try it.
Bottom line
Design wkhtmltopdf documents around old-school flow, floats, tables, explicit dimensions and print rules. Regard flexbox and Grid as unsafe, test every advanced effect on the exact executable, and move to a current Chromium-based renderer when modern CSS or JavaScript is a requirement.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsFrequently Asked Questions
Does adding a modern doctype make wkhtmltopdf use a newer CSS engine?
No. A doctype can affect standards or quirks behavior, but it cannot update the Qt WebKit engine embedded in the wkhtmltopdf binary.
Can a stylesheet contain unsupported declarations safely?
Usually yes: wkhtmltopdf generally ignores declarations it does not understand. The danger is silent layout loss, so provide fallbacks and inspect the rendered PDF.
Is every 0.12.6 package identical?
No. Packaging, patched-Qt status, fonts, operating system and command-line flags can change results. Record and test 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.
