To render a gradient in a table cell with wkhtmltopdf, keep a solid color as the first declaration, add the legacy Qt WebKit -webkit-gradient() declaration, and make sure backgrounds are enabled. Use --print-media-type only when the relevant CSS is inside @media print. Then test the exact wkhtmltopdf binary and platform you deploy, because Qt WebKit builds do not all behave identically.
The most dependable workflow is: prove that a solid background prints, verify the selected media rules, add the legacy gradient syntax, and reduce failures to a one-cell test page before changing your production template.
A minimal table-cell example
This example uses a solid fallback followed by the gradient form demonstrated for older Qt WebKit renderers. The fallback matters: if the gradient parser or renderer cannot draw the second declaration, the cell still has a usable color.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
table {
border-collapse: collapse;
width: 100%;
}
td {
border: 1px solid #555;
padding: 18px;
color: #fff;
font: 16px Arial, sans-serif;
}
td.gradient-cell {
background: #dddddd;
background: -webkit-gradient(linear, center top, center bottom,
from(#dddddd), to(#777777));
}
</style>
</head>
<body>
<table>
<tr>
<td class="gradient-cell">Gradient cell</td>
<td>Unstyled cell</td>
</tr>
</table>
</body>
</html>Save it as gradient-test.html, then render it:
wkhtmltopdf --background gradient-test.html gradient-test.pdf--background is documented as the default, but specifying it makes the command’s intent explicit. Do not use --no-background; that option suppresses backgrounds.
#1 Best Overall
Understand the two settings that control what you see
Background painting
The command-line switch --background allows background colors and images to print. Its inverse, --no-background, disables them. In a library integration, the equivalent setting is web.background=true. Check the generated command or option object first: a wrapper may be adding --no-background even when your HTML is correct.
Screen media versus print media
--print-media-type tells wkhtmltopdf to apply print media rules instead of screen media rules. It does not add support for CSS that the renderer cannot parse. If your gradient is in an ordinary stylesheet or under @media screen, selecting print media can make it disappear.
Use one of these patterns deliberately:
/* Always available to the selected media type */
td.gradient-cell {
background: #dddddd;
background: -webkit-gradient(linear, center top, center bottom,
from(#dddddd), to(#777777));
}
/* Only used when --print-media-type is selected */
@media print {
td.print-gradient {
background: #dddddd;
background: -webkit-gradient(linear, center top, center bottom,
from(#dddddd), to(#777777));
}
}If you intentionally keep the rule in @media print, render with:
wkhtmltopdf --background --print-media-type gradient-test.html gradient-print.pdfFor a library, select the corresponding load.printMediaType=true option. If the page is designed for screen media, leave print-media selection off and compare both outputs before changing CSS.
Why the legacy declaration is useful
wkhtmltopdf uses a Qt WebKit rendering engine. Older WebKit implementations may recognize the prefixed gradient syntax even when they do not handle the modern linear-gradient() form consistently. The compatibility pattern is therefore:
- Declare a solid color first.
- Declare
-webkit-gradient(linear, ...)second. - Keep the two colors close enough that the fallback remains acceptable.
For a vertical gradient, center top is the starting point and center bottom is the ending point. A horizontal version can use left center and right center. Test the exact direction in your PDF rather than assuming modern CSS coordinate behavior.
td.horizontal-gradient {
background: #2d6cdf;
background: -webkit-gradient(linear, left center, right center,
from(#2d6cdf), to(#7b2cbf));
}Keep the fallback declaration even after a successful test. It protects the output if a deployment uses a different wkhtmltopdf build or if the gradient is ignored.
Use this diagnostic sequence
- Record the renderer. Run
wkhtmltopdf --versionand record the complete version, whether Qt is patched, operating system, and installation source. - Confirm background output. Render a cell with only
background: red;and no gradient. If that color is absent, inspect the command for--no-backgroundand set--backgroundexplicitly. - Check media rules. Search the stylesheet for
@media printand@media screen. Render once with and once without--print-media-typeif you are unsure which branch contains the cell rule. - Add the compatibility syntax. Put the solid declaration first and the legacy
-webkit-gradient()declaration immediately after it. - Reduce the page. Use one table, one row, one cell, local CSS, and two simple colors. Remove JavaScript, external fonts, images, and unrelated layout rules.
- Compare the PDF. Check the cell at normal zoom and at high zoom. A subtle gradient can look like a solid fill at thumbnail size.
- Promote the fix carefully. Apply the tested declarations to the production template, then repeat the render on the same operating system and binary used in deployment.
Common failures and precise fixes
The cell is white or transparent
First render a solid color. If it also fails, backgrounds are disabled or the rule is not being selected. Remove --no-background, add --background, and verify selector specificity. In a library integration, inspect web.background and set it to true.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteThe solid color appears, but the gradient does not
This indicates that the cell rule is being applied but the gradient declaration is not understood or is being overridden. Retain the solid fallback, add the legacy -webkit-gradient() form, and remove later declarations that replace background. Test with a very large color difference so the result is unambiguous.
The gradient works without --print-media-type but disappears with it
Print media is selecting a different rule set. Move the tested declaration into the active print rule, or stop selecting print media if the design is intended for screen media. The switch changes media selection; it does not repair unsupported CSS.
Images or other background resources vanish in print mode
Issue reports describe image-loading problems in particular configurations, including a report for wkhtmltopdf 0.12.5 where an image referenced only inside @media print rendered after it was also referenced in default media, and a report for 0.12.6 with patched Qt where images disappeared when print media was selected. These are setup-specific reports, not proof that every 0.12.5 or 0.12.6 build behaves that way.
Use the reports as a diagnostic lead: reference a required resource in the default stylesheet as well, compare output with and without --print-media-type, and record your binary and platform. Do not treat that workaround as a universal gradient fix.
Recommended Free Tools
It works locally but not in production
Compare the exact executable, version, Qt patch level, operating system, CSS files, and command-line flags. A package supplied by one operating system can differ from another package carrying the same nominal wkhtmltopdf version. Archive the minimal HTML, CSS, command, and resulting PDF with your deployment notes.
Library and automation equivalents
The command-line concepts map directly to common library option objects:
| Need | Command line | Library setting |
|---|---|---|
| Print backgrounds | --background |
web.background=true |
| Suppress backgrounds | --no-background |
Set the background option false |
| Select print CSS | --print-media-type |
load.printMediaType=true |
Names and nesting vary by language binding, so inspect the binding’s generated command or debug log. The rendered behavior should still be validated with the same one-cell fixture.
Performance, reliability and operational cost
Performance
A two-color CSS gradient is usually cheaper to render than an image asset, but page-wide layout, fonts, scripts and remote resources can dominate conversion time. Keep the diagnostic fixture local and small. Once it works, measure your real document with the same timeout and concurrency settings used in production rather than extrapolating from the fixture.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Reliability
Pin the wkhtmltopdf binary and operating-system image, keep a copy of the version output, and add a regression PDF containing a known gradient cell. Re-render that fixture after upgrades. This catches changes in Qt WebKit behavior before they affect invoices, reports or exports.
Cost
wkhtmltopdf itself is a command-line conversion step, so your cost comes from the machine time, storage and maintenance of the environment running it. The supplied compatibility evidence does not establish a universal runtime or pricing figure; benchmark your own documents if capacity planning matters.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When to stop debugging this renderer
If the minimal local fixture still shows only the solid fallback after you have confirmed backgrounds, media selection and the legacy syntax, the remaining variable is likely the specific wkhtmltopdf/Qt WebKit build. At that point, either keep the documented fallback or evaluate a renderer with a more current engine. Do not claim that a different renderer will produce identical pagination without testing the actual document.
Or skip the browser setup
If your goal is a clean screenshot or PDF of a hosted table rather than reproducing wkhtmltopdf’s Qt WebKit behavior, ScreenshotNeo can capture the page through one API 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, blank pages, timeouts, failed loads and cache hits are not billed, and 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.
Use custom CSS or JavaScript, a selector wait, network-idle waiting, a chosen viewport or device preset, dark mode, retina scale, resource blocking, headers, cookies, user-agent, timezone and geolocation when the hosted page needs them. For PDFs, you can set paper size, margins, landscape mode and page ranges. These controls change how the page is captured; they do not make wkhtmltopdf’s CSS engine more compatible.
See the ScreenshotNeo API documentation for authentication and all options. The following requests target a page containing the test table:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/gradient-table.html -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com/gradient-table.html"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com/gradient-table.html' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo includes 1,000 shots per month free with no card. Paid plans start at $5 for 3,000 shots; the listed plans are Starter $5/3,000, Growth $15/15,000, Pro $39/60,000, Scale $99/250,000 and Business $249/1,000,000. Yearly billing gives two months free, and every feature is available on every plan.
Sign up for the free ScreenshotNeo plan to try a clean capture without a card.
Frequently Asked Questions
Will ScreenshotNeo reproduce the exact PDF produced by wkhtmltopdf?
No. ScreenshotNeo captures the hosted page with its own service, while wkhtmltopdf uses Qt WebKit. Use the one-cell wkhtmltopdf fixture when engine compatibility is the requirement; use ScreenshotNeo when a clean hosted-page capture is the requirement.
Should I replace the legacy syntax with modern linear-gradient()?
Keep the solid fallback and test the modern form separately. The documented compatibility lead for older Qt WebKit is the prefixed -webkit-gradient() declaration, so do not remove it solely because a modern browser accepts newer syntax.
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.
