Why Flexbox Is Not Working in wkhtmltopdf—and How to Fix It

Flexbox is unreliable in wkhtmltopdf because wkhtmltopdf uses an obsolete Qt/WebKit rendering engine. Qt 4 has not been supported since 2015, and its WebKit engine has not been updated since 2012. Modern Flexbox declarations may therefore be ignored or rendered with different rules. The dependable fix is to replace Flexbox with tables, carefully sized inline-blocks, or floats—or move the PDF job to a maintained engine when the design requires modern CSS.

Why display:flex fails in wkhtmltopdf

wkhtmltopdf is not a current Chromium or Firefox browser. Its rendering stack is based on Qt 4 and an old WebKit fork. The project’s status summary dates Qt 4 support to 2015 and the WebKit update to 2012. CSS that works in a current browser can consequently be ignored, partially implemented, or laid out according to old vendor behavior.

#	Preview	Product	Price
1		PDF Explained: The ISO Standard for Document Exchange	$14.41	Buy on Amazon
2		Adobe Acrobat 6 PDF For Dummies	$13.00	Buy on Amazon
3		Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware...	$13.39	Buy on Amazon

This is a long-standing compatibility problem rather than a missing semicolon. A 2014 wkhtmltopdf issue reported that a Flexbox test rendered “as if the flex properties were not present” in a 0.12-era Windows build. The reporter also tried -webkit- declarations without success. A 2021 report against 0.12.6 with patched Qt on Ubuntu 20.04 and Debian 10.9 described the same failure with both unprefixed and prefixed CSS. A related 2021 wkhtmltoimage report likewise found that adding display:flex made no visible difference; suggestions for legacy prefixes were not confirmed as a solution.

Those reports are individual cases, not a compatibility guarantee for every binary. They do establish the practical rule: treat modern Flexbox as unsupported or unreliable in wkhtmltopdf and test any workaround with the exact executable used in production.

#1 Best Overall

Sale

PDF Explained: The ISO Standard for Document Exchange

$14.41

Buy on Amazon

Why adding -webkit-flex usually does not repair it

Prefixes only help when the underlying engine contains a compatible implementation behind that prefix. Old WebKit implementations used several incompatible Flexbox drafts, while current CSS uses a later specification. A declaration such as display:-webkit-flex may be parsed, yet properties such as flex, justify-content, align-items, ordering, wrapping, or intrinsic sizing can still be ignored or interpreted differently.

Adding both forms can be harmless for a browser matrix, but it is not a reliable wkhtmltopdf fix:

.row {
  display: -webkit-flex;
  display: flex;
  -webkit-justify-content: space-between;
  justify-content: space-between;
}

If the generated PDF still stacks items, overflows, or leaves the container unchanged, stop iterating on prefixes and use a legacy layout pattern or a different renderer.

First, reproduce the failure with the production binary

1. Record the exact wkhtmltopdf version, operating system, package source, and whether it is a patched-Qt build.
2. Create a minimal HTML file containing only the container, two or three children, and the CSS under investigation.
3. Render that file with the same command-line flags and executable used by your application.
4. Inspect the PDF, not just the page in Chrome or Firefox. A browser preview cannot prove that wkhtmltopdf will calculate the same layout.

Keep the minimal file and command in your bug report. Distribution packages and patched builds can differ, so “wkhtmltopdf 0.12” alone is not enough information to reproduce a layout.

Reliable replacements for Flexbox

Use a table for rows and columns

For invoices, report headers, address blocks, and two-column metadata, tables are generally the most predictable choice in a legacy WebKit PDF engine. Give the table and cells explicit widths, padding, borders, and vertical alignment.

<table class="meta">
  <tr>
    <td class="label">Invoice number</td>
    <td class="value">INV-1042</td>
  </tr>
  <tr>
    <td class="label">Due date</td>
    <td class="value">30 October 2026</td>
  </tr>
</table>

.meta {
  width: 100%;
  border-collapse: collapse;
  table-layout: fixed;
}
.meta .label { width: 35%; padding: 6px; vertical-align: top; }
.meta .value { width: 65%; padding: 6px; vertical-align: top; }

For a header with two fixed areas, use two cells and set widths as percentages that total 100 percent. Avoid relying on automatic content sizing when long customer names or translated text can change the available width.

Use inline-block for small horizontal groups

Inline blocks work for badges, compact controls, or a short two-column group. Set an explicit width and vertical-align:top. HTML whitespace between inline-block elements consumes horizontal space, so either remove the whitespace or leave enough width for it.

.item {
  display: inline-block;
  width: 48%;
  vertical-align: top;
  box-sizing: border-box;
  padding: 8px;
}

Do not assume modern flex shrinking will save an over-wide row. Calculate the widths, padding, borders, and whitespace together.

Rank #2

Sale

Adobe Acrobat 6 PDF For Dummies

• Used Book in Good Condition

$13.00

Buy on Amazon

Use floats for a simple left/right split

Floats remain useful when one block belongs on the left and another on the right. Give both children explicit widths and clear the parent.

.left  { float: left;  width: 48%; }
.right { float: right; width: 48%; }
.clearfix:after {
  content: "";
  display: table;
  clear: both;
}

Without clearing, the parent can collapse and following content may overlap or move unexpectedly. Keep the combined widths below 100 percent to leave room for borders and rounding.

Reserve absolute positioning for fixed-size elements

Absolute positioning can place a logo, stamp, or invoice header at a known coordinate. It becomes brittle when text wraps, the page size changes, or content grows. Use it only for controlled, fixed-size elements and keep normal-flow content clear of the positioned area.

Simplify the whole component, not only display

Replacing Flexbox can expose other unsupported dependencies. CSS Grid, custom properties, newer sizing functions, and responsive calculations may fail independently in old WebKit. Flatten the component to ordinary selectors and explicit values. Replace variables with literal colors and dimensions, avoid relying on min(), max(), or content-based sizing, and provide fixed page-oriented widths.

Also check assets. A missing local stylesheet, font, or image can make a correct layout look broken. Use valid file URLs and configure the appropriate local-file-access option for your deployment. Verify that every resource is reachable from the rendering process rather than from your interactive browser session.

A practical migration decision

Stay with wkhtmltopdf when the document is deliberately simple, the existing output is stable, and replacing the layout is cheaper than changing the rendering pipeline. Migrate when the template depends on Flexbox or Grid, modern fonts or SVG behavior, responsive calculations, or JavaScript-driven layout.

The wkhtmltopdf project status guidance points to WeasyPrint or the commercial Prince engine for controlled report generation, and to browser-based tooling for pages that depend on dynamic JavaScript. Evaluate candidates against:

• Required CSS and JavaScript feature coverage.
• Headers, footers, page breaks, and pagination controls.
• Font, SVG, image, and local-file handling.
• Licensing and deployment cost.
• Determinism, security maintenance, and operational support.

Migration is not automatically simpler: templates may need new pagination rules, fonts may render differently, and a new engine must be tested on every target document.

Rank #3

Sale

Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems

• Used Book in Good Condition

$13.39

Buy on Amazon

Debugging checklist

• Everything stacks: confirm the PDF is produced by the binary and version you think it is; then replace the container with a table.
• Prefixes did nothing: expected for many 0.12 builds; do not treat prefixes as proof of Flexbox support.
• Only production fails: compare patched-Qt status, operating system, command flags, and input HTML with your local run.
• Columns wrap unexpectedly: subtract padding, borders, and inline-block whitespace from the available width; use explicit percentages or fixed widths.
• Following content overlaps floats: add a clearing element or the clearfix rule.
• Styles appear missing: check stylesheet paths, file URL syntax, local-file-access configuration, and permissions for fonts and images.
• Browser and PDF disagree: trust the PDF generated by the production binary and reduce the page to a minimal reproduction.
• JavaScript layout is absent: confirm the page is fully rendered before capture; if the design fundamentally depends on dynamic browser behavior, choose a browser-based PDF workflow.

Or skip the browser setup

If your actual requirement is a clean screenshot or PDF of a web page rather than maintaining wkhtmltopdf CSS, ScreenshotNeo provides a single HTTP request. It accepts cookie and consent banners like a visitor, removes more than 60 known consent platforms plus newsletter popups and chat widgets before capture, and lets you turn each cleanup step off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.

Example using cURL (see the ScreenshotNeo documentation):

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

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}`);

ScreenshotNeo also supports full-page and element captures, device presets and custom viewports, retina scale, dark mode, PDF paper and margin settings, custom CSS and JavaScript, clicks, waits, blocked resources, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. Its parameter names are compatible with those used by other screenshot APIs, easing a switch.

The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is on every plan. Create a free ScreenshotNeo account to try it.

FAQ

Does wkhtmltopdf support any Flexbox at all?

Behavior varies by build and property. Some isolated declarations may appear to work, but the engine cannot be treated as a reliable implementation of current Flexbox semantics.

Should I downgrade or change wkhtmltopdf flags?

Changing versions or flags can alter output, but it does not turn the old WebKit engine into a modern CSS engine. Reproduce first, then choose a simpler layout or migrate.

Is this problem limited to PDFs?

No. The related wkhtmltoimage report shows the same class of issue in image output, because both tools rely on the legacy rendering stack.

Frequently Asked Questions

Can a CSS reset make Flexbox work in wkhtmltopdf?

A reset may remove conflicting styles, but it cannot add missing engine support. Use a minimal test and a legacy layout pattern instead.

Are tables suitable for responsive web pages too?

They are recommended here for fixed PDF output. Keep your responsive browser stylesheet separate if the same markup must serve an interactive page.

What should I preserve when changing PDF engines?

Retest pagination, headers and footers, fonts, SVGs, images, local resources, JavaScript timing, licensing, and deployment behavior.

Quick Recap

SaleBestseller No. 1

PDF Explained: The ISO Standard for Document Exchange

$14.41

SaleBestseller No. 2

Adobe Acrobat 6 PDF For Dummies

Used Book in Good Condition

$13.00

SaleBestseller No. 3

Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems

Used Book in Good Condition

$13.39

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.