What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Short answer: add --print-media-type when you want wkhtmltopdf to evaluate CSS for the print media type instead of the screen media type. The manual lists --no-print-media-type as the default. The switch controls media selection; it does not repair missing stylesheets, unsupported CSS, failed network requests, or every layout problem.
This setting applies to PDF conversion. The C API documents the corresponding load.printMediaType property and explicitly says it has no effect when using wkhtmltoimage.
What --print-media-type actually changes
It selects the print media type
CSS can contain rules that apply to all media, rules limited to screen, and rules limited to print. When you run:
wkhtmltopdf --print-media-type input.html output.pdfwkhtmltopdf asks its rendering engine to use print media while creating the PDF. A rule such as @media print { ... } is therefore eligible to match. A rule inside @media screen { ... } is not the selected media rule.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →#1 Best Overall
The option is a media-selection request, not a separate print stylesheet compiler. The normal CSS cascade still determines which declarations win: unqualified rules can apply, media-qualified rules can override them, and specificity and source order still matter.
The default is not print media
The usage manual lists --no-print-media-type as the default. If you omit --print-media-type, print media is not selected. Make the choice explicit in build scripts so a future reader can see whether the PDF is intended to follow screen or print rules:
# Use the selected print stylesheet rules
wkhtmltopdf --print-media-type report.html report.pdf
# Leave print media unselected (the documented default)
wkhtmltopdf --no-print-media-type report.html report-screen-media.pdfDo not read the default as a promise that every screen-only rule will look identical to a current browser window. The media choice is only one part of rendering.
It is a PDF setting, not an image-converter setting
If your pipeline calls wkhtmltoimage, changing the PDF option will not alter the image output. The C API documentation states that load.printMediaType has no effect for wkhtmltoimage. Test the converter you actually deploy.
Rank #2
How ordinary and print-only CSS are combined
Unqualified rules are still part of the cascade
A declaration outside any media query is generally eligible for both screen and print. For example:
<style>
body {
font-family: sans-serif;
color: #222;
}
.invoice-total {
font-weight: 700;
}
@media print {
body {
color: #000;
}
.screen-help {
display: none;
}
}
@media screen {
.screen-help {
display: block;
}
}
</style>With --print-media-type, the print declarations become eligible, so .screen-help can be hidden and the print color can override the earlier color. The unqualified font and invoice weight remain candidates unless another declaration with greater specificity or later source order replaces them.
Why a report can appear to “lose” normal styles
A historical issue reported that print rules appeared while styles without an explicit media type seemed absent. That issue is a user’s 2015 question, not a verified description of universal wkhtmltopdf behavior. If you see the same symptom, do not solve it by copying every rule into @media print immediately. First establish whether the stylesheet was loaded and whether the cascade is doing what the source says.
Common explanations include a stylesheet URL that the converter cannot reach, a relative path that resolves differently from the command-line working directory, a later print rule that overrides a broad rule, or differences between wkhtmltopdf binaries. The project’s own status page describes the underlying Qt/WebKit stack as old, so modern CSS behavior cannot be assumed from a current browser.
Recommended Free Tools
A minimal, repeatable test
Reduce the question to one HTML file before investigating a large application. This file deliberately gives screen and print media visibly different results:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Media test</title>
<style>
body { background: #f4f4f4; color: #222; font: 16px sans-serif; }
.screen-only { display: block; }
.mode::after { content: "screen/default"; }
@media print {
body { background: white; color: black; }
.screen-only { display: none; }
.mode::after { content: "print"; }
}
</style>
</head>
<body>
<p class="mode">Media mode: </p>
<p class="screen-only">This text should disappear in print media.</p>
<p>This paragraph has no media restriction.</p>
</body>
</html>- Save the file as
media-test.html. - Run
wkhtmltopdf --print-media-type media-test.html print.pdf. - Run
wkhtmltopdf --no-print-media-type media-test.html default.pdf. - Open both PDFs and compare the generated label, the hidden paragraph, and the colors.
- If the minimal file behaves correctly, add your real stylesheets and assets one at a time until the difference appears.
This isolates media selection from application routing, templating, authentication, JavaScript, and external resources. Record the exact executable path and version for each run; distributions and patched-Qt builds can differ.
Troubleshooting print-media problems
| Symptom | Likely explanation | What to check |
|---|---|---|
@media print rules never appear |
Print media was not selected, or the stylesheet was not loaded. | Use --print-media-type; verify the stylesheet URL, file path, and response; then repeat with the minimal file. |
| Unqualified rules seem to vanish | A later or more-specific declaration may override them, or the old renderer may parse the source differently than expected. | Inspect the cascade, remove competing rules, and test the exact binary with a reduced document. The historical issue does not establish a general defect. |
| Screen-only content remains visible | The content has no effective print rule, or a stronger declaration wins. | Add a narrowly scoped print declaration, check specificity and source order, and confirm that the print stylesheet loaded. |
| CSS works in a browser but not in the PDF | wkhtmltopdf uses a legacy Qt/WebKit engine rather than the browser you tested. | Check for engine-dependent CSS, unsupported layout features, external fonts, and JavaScript-generated markup. Reproduce with a small static page. |
| PDF and image output disagree | The media option is for PDF loading; the C API says it has no effect for wkhtmltoimage. |
Test PDF and image conversion separately and configure each pipeline independently. |
| Results change after deployment | The server may run a different wkhtmltopdf build, Qt patch set, working directory, or network policy. | Log the binary version and command, use deterministic asset URLs, and compare a known-good fixture during deployment. |
Check resources before changing CSS
A PDF cannot apply a stylesheet it never received. Confirm that every external CSS file, font, image, and script is reachable from the conversion environment. Relative URLs should be tested from the same directory and account used by the production process. If a page requires authentication, make sure the converter is actually receiving the required session or headers; otherwise the HTML may be a login page rather than the report you inspected in a browser.
Separate loading failures from cascade failures
Temporarily inline a small CSS rule in the HTML. If the inline rule responds to --print-media-type but the linked file does not, investigate URL resolution or access controls. If neither responds, reduce the document again and verify the command and executable. This prevents a missing resource from being misdiagnosed as a media-query bug.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →What the Qt/WebKit age means for production
The wkhtmltopdf project status page says Qt 4 has not been supported since 2015 and that the WebKit in Qt 4 had not been updated since 2012. Those are project-reported dates, not a fresh compatibility audit, but they explain why a page designed for a current browser can diverge in PDF output. Treat print-media selection as a compatibility choice, not a guarantee of modern CSS support.
The same status page carries a serious warning: “Do not use wkhtmltopdf with any untrusted HTML – be sure to sanitize any user-supplied HTML/JS, otherwise it can lead to complete takeover of the server it is running on!” Keep report templates and user-provided markup separated, sanitize any accepted HTML and JavaScript, and run conversion with the least privilege practical for your deployment.
When another renderer is a better fit
The project status page itself points to different alternatives for different workloads:
- Controlled HTML report generation: it names WeasyPrint or Prince as tools to consider.
- Pages that depend on dynamic JavaScript: it names Puppeteer as an option to consider.
These are project suggestions, not a head-to-head benchmark or endorsement. Choose by the rendering engine and CSS features your documents require, whether JavaScript must execute, how the tool is maintained, your deployment and security model, and any commercial licensing requirements. The available official material does not establish current prices, performance rankings, or complete feature matrices for these alternatives.
Best Value
Performance, reliability and cost planning
Make output reproducible
- Pin the wkhtmltopdf executable and record its version.
- Keep a fixture containing screen-only, print-only, and unqualified rules.
- Use stable asset URLs and verify that fonts and images are available to the conversion process.
- Compare generated PDFs after upgrades rather than assuming a browser screenshot predicts the result.
Measure your own workload
No official statistic in the cited materials establishes a universal conversion speed or failure rate. Measure representative documents in the environment where they will run, including network-dependent pages and the largest reports. Track timeout, blank-output, and resource-loading failures separately from CSS mismatches; they require different fixes.
Budget for maintenance, not just execution
The supplied project material does not establish a current wkhtmltopdf price or a supported commercial edition. Your practical costs are therefore deployment, isolation, template maintenance, and the engineering time required when legacy rendering diverges from browser output. If your documents require current browser features or untrusted content handling, include the cost of evaluating a maintained alternative rather than treating the command-line binary as a complete solution.
Or skip the browser setup
If you need a clean screenshot of a publicly reachable website rather than a locally rendered PDF, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.
Use the API documentation at https://screenshotneo.com/docs/ for all parameters. A basic call is:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorscurl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', data));ScreenshotNeo also exposes an MCP server for AI agents, including Claude, Cursor, and other MCP clients, with take_screenshot, get_page_info, and capture_pdf tools. Its 63 options include full-page capture with lazy images loaded, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF paper and page controls, custom CSS and JavaScript, click and wait actions, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed links, asynchronous webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs are accepted to ease migration.
Quick Recap
| Plan | Allowance | Price |
|---|---|---|
| Free | 1,000 shots per month | $0, no card |
| Starter | 3,000 shots | $5 |
| Growth | 15,000 shots | $15 |
| Pro | 60,000 shots | $39 |
| Scale | 250,000 shots | $99 |
| Business | 1,000,000 shots | $249 |
Every feature is available on every plan, and yearly billing gives two months free. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. To try it with 1,000 free screenshots a month and no card, create a ScreenshotNeo account.
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.
