Recommended Free Tools
Pass your CSS file to wkhtmltopdf with --user-style-sheet. A complete conversion looks like this:
wkhtmltopdf --user-style-sheet /path/to/user.css input.html output.pdfThe file must be readable by the wkhtmltopdf process. In application code, use the equivalent web.userStyleSheet setting with a path or URL.
What --user-style-sheet does
wkhtmltopdf documents --user-style-sheet <path> as a stylesheet to load with every page. It injects CSS into the web-page rendering used for the conversion; it is not a Qt Widgets stylesheet.
The option changes how HTML is rendered before the PDF is written. It does not modify the source HTML file. You can therefore keep a site’s original markup and apply print-specific rules, accessibility adjustments, or a consistent house style at conversion time.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Use an absolute filesystem path when the converter runs locally or in a service. A URL can also be used where the installed build can reach it, but that introduces a network dependency and version-specific URL-handling differences.
Command-line setup
- Create the CSS file. Put only the rules you want applied during conversion in a file such as
/srv/pdf/user.css. - Make the file readable. Check the account, container, or service that launches wkhtmltopdf—not just the account you use interactively.
- Pass the option. Use the command shown in the introduction, replacing the three paths with values valid in your environment.
- Open the resulting PDF. Confirm that the rule is visible in the rendered output rather than judging only from the HTML in a browser.
For a quick diagnostic, start with an unmistakable rule, such as a large color change or a temporary outline. Once the file is proven to load, replace that diagnostic rule with the production CSS.
A minimal example
Suppose input.html and user.css are in /home/reports/. Run:
wkhtmltopdf --user-style-sheet /home/reports/user.css /home/reports/input.html /home/reports/output.pdfRelative paths can work when the current working directory is what you expect, but absolute paths remove a common source of failures in scheduled jobs, web workers, and containers.
Make the CSS reachable to the converter
The stylesheet is loaded by the wkhtmltopdf process, so “the file exists on my machine” is not sufficient. The process must be able to resolve and read the path from its own filesystem view.
- Service account: a web server or queue worker may run as a different user and lack permission to read the file.
- Container: the host path must be mounted at the same path, or you must pass the path that exists inside the container.
- Remote worker: a path on your laptop is unavailable to a worker running elsewhere; use a path or URL available to that worker.
- Sandboxed local files: inspect the installed binary’s local-file options. The official usage manual documents
--allow <path>for allowing files or folders to be loaded.
Builds differ in their defaults and patches. Run wkhtmltopdf --extended-help on the exact binary that performs the conversion and follow the local-file-access behavior it reports. Do not assume that a distribution package has the same defaults as another package or fork.
CSS files, URLs, and local-file access
Filesystem path
A filesystem path is usually the simplest choice for a CSS file deployed with your application. Keep the file in a directory readable by the conversion process and pass the path exactly as that process sees it.
URL value
The library setting accepts a URL or path, and some command-line builds can load a URL as well. A URL requires the converter to resolve the host, connect successfully, and obtain the response before rendering. If the page is generated in an isolated network, a remote stylesheet may fail even though the same URL works in your desktop browser.
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
Data URLs and historical behavior
Qt WebKit’s archived API reference shows the underlying user-style-sheet mechanism through QWebSettings::setUserStyleSheetUrl, including a CSS data-URL example. That is useful implementation history, not a promise that every current wkhtmltopdf package accepts every URL scheme. Treat the target binary’s own help and a minimal conversion as authoritative.
Using the library interface
When you embed libwkhtmltox through a language binding, set the web setting named web.userStyleSheet to a path or URL:
web.userStyleSheet = "/srv/pdf/user.css"The exact function used to assign a web setting depends on your binding, but the setting name and value are the important parts. Configure it on the web-page settings object used for the conversion, then create the PDF as usual.
| Interface | Setting | Value | Typical use |
|---|---|---|---|
| Command line | --user-style-sheet <path> |
Path supplied to the wkhtmltopdf process | Shell scripts, CI jobs, and one-off conversions |
| libwkhtmltox | web.userStyleSheet |
URL or filesystem path | Applications that create PDF jobs in code |
Both interfaces ultimately depend on the same condition: the rendering process must be able to access the stylesheet.
Global and per-object placement
The usage manual describes options that can be specified globally or per object. In a multi-object command, however, the material does not establish identical placement behavior for every build, wrapper, or invocation pattern. If one document converts several page objects, validate the option with a minimal two-object example and inspect the exact installed binary’s help.
For predictable deployments, keep the command simple, use one known stylesheet path, and test the actual command line generated by your wrapper. A successful conversion alone does not prove that the user stylesheet was applied.
Do not confuse it with Qt Widgets stylesheets
QApplication::setStyleSheet and other Qt Style Sheets (QSS) APIs style desktop application widgets. They do not set the CSS injected into an HTML page rendered by wkhtmltopdf. For HTML-to-PDF output, use the wkhtmltopdf command-line option or the web.userStyleSheet web setting.
Verification checklist
- Print the resolved path immediately before launching wkhtmltopdf.
- Check that the launching account can read the file.
- When using a container, verify the file exists inside the container.
- Use
wkhtmltopdf --extended-helpfrom the same installation used by the job. - Test with a conspicuous temporary CSS rule, then remove it after verification.
- Compare a conversion with and without the option so you know the change came from the user stylesheet.
- For a remote URL, test DNS, network access, authentication requirements, and response availability from the converter’s environment.
Troubleshooting a stylesheet that is not applied
| Symptom | Likely cause | Fix |
|---|---|---|
| No visible change | The path is wrong, relative to an unexpected working directory, or unreadable. | Use an absolute path, check permissions as the launching account, and add a temporary unmistakable rule. |
| It works in a terminal but not in production | The service, container, or remote worker has a different filesystem or user. | Check the process identity and the path inside that environment; mount or deploy the CSS there. |
| A local file is blocked | The build’s local-file policy prevents access. | Read the installed binary’s extended help and configure the documented local-file options, including --allow <path> where appropriate. |
| A URL stylesheet fails intermittently | The converter cannot consistently reach the URL, or the build handles that URL scheme differently. | Prefer a local deployed file for deterministic jobs, or verify network access from the conversion host and test the exact build. |
| Only some objects receive the style | Option placement or wrapper behavior differs in a multi-object command. | Reduce the command to a minimal example, test global and per-object placement, and consult that binary’s help. |
| Changing Qt application styling has no effect | QSS is styling widgets, not the HTML renderer. | Set --user-style-sheet or web.userStyleSheet instead. |
| A data URL works on one machine but not another | URL-scheme support varies among archived Qt WebKit code, wkhtmltopdf packages, and forks. | Use a normal path or a tested URL and treat the target build’s behavior as authoritative. |
Reliability and maintenance considerations
Prefer deterministic inputs for automated PDFs
A local CSS file deployed alongside the job avoids DNS, network, and remote-server failures. It also makes the input versionable with the application that produces the PDF.
Outdated 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 matchPC 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 & 11Best Value
Keep environment differences visible
wkhtmltopdf packages can be built with different Qt revisions, patches, and defaults. Record the binary version and test the same package in development, CI, and production. The official command reference is the right place to confirm supported switches for that installation.
Do not infer performance from documentation
The official material does not publish a general timing or throughput figure for user stylesheets. Expect the normal cost of reading the CSS and, for a URL, the cost and risk of a network fetch; measure your own workload if conversion latency matters.
Or skip the browser setup
If your actual goal is to capture a hosted webpage as an image or PDF rather than maintain a local wkhtmltopdf pipeline, ScreenshotNeo provides a website screenshot API. It can apply custom CSS and JavaScript, while handling page-cleanup steps before capture.
One GET request is enough:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for the available parameters and response headers. The same request from Python is:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesimport 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)And in 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}`);Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, and timeouts are not billed, and the response identifies the page verdict and billing status with X-Page-Verdict and X-Billed headers. ScreenshotNeo also has an MCP server so Claude, Cursor, and other MCP clients can call take_screenshot, get_page_info, and capture_pdf. 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.
Frequently asked questions
Frequently Asked Questions
Does the user stylesheet rewrite my HTML source?
No. It affects the rendering session used to produce the PDF; your input HTML file remains unchanged.
Can I rely on the same URL schemes in every wkhtmltopdf package?
No. Qt WebKit’s archived API documents URL-based injection, but patched, distro, and forked builds can differ. Test the exact binary you deploy.
What should I test first in a production incident?
Check the resolved CSS path and process identity, then run the installed binary’s extended help and reproduce the conversion with a conspicuous temporary rule.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
