Short answer: add --print-media-type when you want wkhtmltopdf to evaluate CSS for the print media type instead of its default screen media type. Rules inside @media print can then apply, while ordinary (unqualified) rules remain part of the cascade unless another rule overrides them. The switch selects a media context; it does not repair missing stylesheets, inaccessible assets, unsupported CSS, or every layout problem.
What --print-media-type actually changes
wkhtmltopdf renders HTML through a Qt/WebKit-based engine. Its command-line manual documents --print-media-type as selecting print media instead of screen media, and lists --no-print-media-type as the default. In practical terms, the converter asks CSS to resolve as though the document were being printed.
That matters for media queries such as:
/* Used in every media context unless overridden */
body {
color: #222;
font: 14px/1.5 Arial, sans-serif;
}
@media print {
body {
color: #000;
}
.screen-only {
display: none;
}
}
@media screen {
.print-only {
display: none;
}
}With the default screen context, the @media screen block is eligible and the @media print block is not. With --print-media-type, the reverse media-specific choice is made. The unqualified body declarations are still eligible in both contexts; normal CSS specificity, source order and inheritance determine which declaration wins.
Therefore, you do not normally need to copy every general rule into @media print. Put shared declarations outside a media query and use @media print only for print-specific changes. If a declaration appears to disappear, investigate the cascade, stylesheet loading and the particular wkhtmltopdf build before assuming that the option intentionally removes unqualified CSS.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Basic commands
Render using print media
wkhtmltopdf --print-media-type input.html output.pdfUse the default screen media behavior
wkhtmltopdf --no-print-media-type input.html output.pdfUse a file URL, an HTTP(S) URL or standard input as your source, provided the input’s resources are reachable by the converter. Keep the output extension consistent with the intended result.
A minimal reproducible test
- Create an HTML file containing one unqualified rule, one
@media screenrule and one@media printrule. - Convert it once with
--no-print-media-typeand once with--print-media-type. - Compare only the declarations controlled by those media blocks.
- Then add your real external stylesheets, images and scripts one at a time. This identifies whether the difference comes from media selection or resource loading.
How CSS is expected to behave
Unqualified rules
A selector outside @media is not “screen-only” merely because the default conversion uses screen media. It is a normal rule that can participate in the cascade for the selected media. For example, a global margin, font family or table border should remain available when print media is selected unless a later, more specific rule changes it.
Print-only rules
Rules enclosed by @media print are intended for printed output. Common uses include hiding navigation, removing interactive controls, changing colors for paper and adjusting page breaks:
@media print {
nav,
.toolbar,
.chat-widget {
display: none;
}
a {
color: #000;
text-decoration: none;
}
.avoid-break {
page-break-inside: avoid;
}
}Screen-only rules
Rules inside @media screen are not selected when the converter is told to use print media. If a layout depends on screen-only declarations, supply an equivalent print rule or move the shared portion outside the media query.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteWhy a print conversion can still look wrong
The media switch does not guarantee support for every modern CSS feature. The wkhtmltopdf project status page describes its Qt 4/WebKit stack as old: Qt 4 has not been supported since 2015, and the WebKit in Qt 4 had not been updated since 2012. Treat those as project-reported compatibility facts, not as a promise that a current desktop browser will match the PDF.
Rank #2
Diagnosing the “print rules work, ordinary styles vanish” report
A historical 2015 user question described print rules appearing while styles without an explicit media type seemed to be ignored. That report is a user’s unresolved question, not authoritative evidence that wkhtmltopdf is supposed to discard unqualified CSS. Work through the following checks instead.
1. Confirm the binary and option
Run the exact executable used by your application and record its version:
wkhtmltopdf --versionDifferent packages may be patched builds with different Qt behavior. Make sure the command shown in logs really includes --print-media-type and is not being replaced by a wrapper’s defaults.
Recommended Free Tools
2. Check stylesheet URLs and paths
Open the source URL from the same machine and user account that runs wkhtmltopdf. Verify that linked CSS files return successfully, that relative paths resolve from the expected document location, and that HTTPS certificates, authentication and redirects are acceptable to the converter. For local files, use correct file:/// URLs and make any required local-file access setting explicit in your deployment policy.
3. Inspect the cascade
Look for a later rule, a more specific selector, an inline style or an !important declaration that overrides the apparently missing property. Also check whether a parent has display:none, zero dimensions or an inherited color that makes a child appear absent.
4. Reduce the document
Remove JavaScript, frameworks and unrelated stylesheets until a small HTML file reproduces the problem. Add resources back incrementally. This distinguishes a media-query issue from malformed markup, timing, a blocked request or unsupported layout code.
5. Check JavaScript timing
If CSS classes or content are added by JavaScript, make sure the page has finished its work before conversion. A print media selection cannot make a script run earlier or make a failed network request succeed.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →What the setting does not affect
It does not apply to wkhtmltoimage
The C API documentation describes load.printMediaType as selecting print media instead of screen media and explicitly says that the setting has no effect for wkhtmltoimage. The documented behavior is therefore specific to page loading for PDF conversion, not a universal switch for every wkhtml family tool.
It does not modernize WebKit
Choosing print media does not add support for newer browser APIs, CSS layout engines or JavaScript features. If your source requires a current browser engine, evaluate a tool whose renderer matches that requirement.
It does not make untrusted HTML safe
The wkhtmltopdf project status page warns: “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!” Sanitize user content, isolate conversion workers and restrict network and filesystem access according to your threat model.
Reliable print CSS patterns for wkhtmltopdf
Keep shared styles shared
/* Shared */
.invoice {
width: 100%;
border-collapse: collapse;
}
/* Print adjustments */
@media print {
.invoice {
font-size: 11pt;
}
.invoice thead {
display: table-header-group;
}
}Use explicit print overrides
When a screen rule sets a dark background, animation or fixed positioning, override that property in @media print rather than duplicating the entire stylesheet. Keep selectors at comparable specificity so the intended print declaration wins predictably.
Make page boundaries deliberate
Use the page-break properties supported by your wkhtmltopdf build, test long tables and avoid relying solely on modern fragmentation properties. A rule that works in a current browser may be ignored or interpreted differently by the legacy engine.
Alternatives when the renderer is the constraint
The project’s status page suggests different alternatives for different workloads: WeasyPrint or Prince for controlled HTML report generation, and Puppeteer for sites that require dynamic JavaScript. Those are project suggestions, not a head-to-head benchmark. Choose based on required CSS support, JavaScript execution, deployment security and—where applicable—commercial licensing and maintenance.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is simply to obtain a clean screenshot or PDF of a URL rather than maintain a wkhtmltopdf rendering stack, ScreenshotNeo provides a single HTTP request. Its API accepts the URL and can return PNG, JPEG, WebP or PDF. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled.
Only clean shots are billed. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and response headers report the page verdict and billing state. ScreenshotNeo also offers an MCP server for Claude, Cursor and other MCP clients, with take_screenshot, get_page_info and capture_pdf tools.
PC 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 & 11Outdated 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 matchOne-call examples
See the full parameter reference in the ScreenshotNeo API documentation.
Best Value
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);All features are included on every plan. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to try it.
Troubleshooting checklist
| Symptom | Likely cause | Action |
|---|---|---|
| Print-specific declarations never appear | The command uses the default screen media or the declaration is overridden. | Confirm --print-media-type, inspect specificity and test a minimal file. |
| General declarations seem missing | Stylesheet failed to load, paths resolve incorrectly, or a later rule overrides them. | Check URLs, redirects, credentials, logs and the cascade. |
| PDF differs from a modern browser | Legacy Qt/WebKit support. | Simplify CSS or evaluate WeasyPrint, Prince or Puppeteer for the workload named by the project. |
| Dynamic content is absent | JavaScript did not finish or a request was blocked. | Verify timing and network access; media selection does not fix asynchronous loading. |
| Image output ignores the setting | The C API documents no effect for wkhtmltoimage. |
Do not rely on this option for image conversion; apply image-specific testing or choose a different renderer. |
Practical decision guide
- Use
--print-media-typewhen your document has intentional@media printrules and you want those rules selected for PDF output. - Keep shared CSS outside media queries and add focused print overrides.
- Investigate resource loading, cascade order, version and JavaScript timing before treating unqualified CSS as unsupported.
- Use a modern or specialized renderer when the legacy Qt/WebKit engine cannot provide the CSS or JavaScript behavior your document needs.
- Sanitize and isolate any conversion involving user-controlled HTML or JavaScript.
Frequently Asked Questions
Is --print-media-type enabled by default?
No. The wkhtmltopdf manual lists --no-print-media-type as the default; pass --print-media-type to select print media.
Do all styles need to be placed inside @media print?
No. Ordinary rules remain eligible for the selected media context. Put only print-specific changes in @media print, then verify the cascade and stylesheet loading if a shared rule appears absent.
Does the option change wkhtmltoimage output?
The C API documentation says load.printMediaType has no effect for wkhtmltoimage.
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.
