Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsUse an SVG through an HTML <img> (or inline the SVG), give it explicit dimensions, and grant wkhtmltopdf access to every local dependency. A reliable baseline is:
<img src="images/diagram.svg" width="600" height="400" alt="Diagram">
Then convert with --images and either --allow /path/to/assets or --enable-local-file-access. This works within the limits of wkhtmltopdf’s Qt WebKit engine; SVG features such as nested images, clip-path, opacity, and preservation of vector data can vary by build.
What wkhtmltopdf actually supports
wkhtmltopdf renders HTML through Qt WebKit. Qt WebKit Widgets provides facilities for HTML, XHTML and SVG documents styled with CSS and scripted with JavaScript. That means an SVG is handled as part of a browser page, not by a dedicated modern SVG-to-PDF engine.
Support is therefore implementation-dependent. The exact wkhtmltopdf version, whether Qt is patched, operating system, packaging and display setup can change the result. The upstream wkhtmltopdf repository was archived on January 2, 2023 and is read-only, so production deployments should pin and document the binary they use.
#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Use the safest inclusion method first
External SVG with <img>
Start with a normal image element and explicit pixel dimensions. A viewBox in the SVG is also important because it defines how the drawing scales:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>body { margin: 0; }</style>
</head>
<body>
<img src="images/diagram.svg" width="600" height="400" alt="Diagram">
</body>
</html>
In the SVG, use a useful root size, for example:
<svg xmlns="http://www.w3.org/2000/svg"
width="600" height="400" viewBox="0 0 600 400">
<rect width="600" height="400" fill="#f4f7fb"/>
<path d="M40 320 L300 80 L560 320" fill="none" stroke="#1464a5" stroke-width="8"/>
</svg>
Explicit dimensions avoid a zero-size or unexpectedly scaled replaced element. Keep the SVG URL correct relative to the HTML file (or use a properly formed absolute URL).
Inline SVG
Inlining can remove a separate file-permission or relative-URL failure. Paste the <svg>...</svg> element directly into the HTML and keep its namespace, viewBox, width and height. It is useful as a diagnostic: if inline markup works while the external file does not, investigate path resolution and local-file permissions.
Avoid relying on <object>
An upstream report (issue #3762) describes an SVG that displayed in a browser but produced a completely blank PDF when referenced with <object data="..." type="image/svg+xml">. The issue was opened on December 21, 2017 and marked invalid; the repository is now archived. Treat <object> as a compatibility risk and prefer <img> or inline SVG.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Allow local files and dependent resources
wkhtmltopdf documents --disable-local-file-access as the default. An SVG may itself load fonts, CSS, images or other files, so permission must cover the whole dependency tree.
Permit one asset directory
wkhtmltopdf --images --allow /absolute/path/to/project/assets input.html output.pdf
--allow restricts access to the supplied path. Use an absolute path and place the SVG and its local dependencies beneath it.
Enable local access broadly
wkhtmltopdf --images --enable-local-file-access input.html output.pdf
This is convenient for a controlled build directory, but it grants wider file access than an allow-list. Do not use it casually when HTML can be influenced by untrusted users.
Make paths reproducible
- Run the command from a known working directory, or use absolute paths in HTML.
- Keep case in filenames exactly as deployed; Linux filesystems are commonly case-sensitive.
- Place external CSS, fonts and nested images under an allowed directory.
- Do not assume a browser’s network access means wkhtmltopdf can reach the same resource.
Control image loading and JavaScript timing
Image loading is documented as enabled by default, but an explicit flag makes intent clear:
wkhtmltopdf --images --allow /path/to/assets input.html output.pdf
Use --no-images only when you deliberately want images omitted. If JavaScript creates the SVG or inserts it after page load, the documented default JavaScript delay is 200 ms. Increase it for a known rendering delay:
wkhtmltopdf --enable-local-file-access --javascript-delay 1000 input.html output.pdf
A delay is not a guarantee that an asynchronous application is finished. Prefer a deterministic page that contains the SVG before conversion. For diagnostics, choose explicit load policies such as --load-error-handling and --load-media-error-handling so failures are visible in logs rather than silently ignored.
A repeatable conversion procedure
- Validate the SVG. Open it in a browser and inspect the root
viewBox, width and height. Remove malformed XML, missing closing tags and unsupported references. - Create the smallest HTML case. Use one
<img>with explicit dimensions and no framework CSS. - Convert with images and permissions. Start with
--images --allow /absolute/path/to/assets; use--enable-local-file-accessonly when appropriate. - Separate dependency failures. Temporarily inline CSS, fonts and nested images. If the simplified SVG works, restore dependencies one at a time.
- Compare external and inline forms. A working inline version points to URL, access or resource-loading problems rather than basic SVG parsing.
- Test the deployed binary. Record the exact version, patched or unpatched Qt, OS, packaging and whether an Xvfb display is involved.
- Inspect the PDF at high zoom. A visually acceptable page at 100% can still contain a rasterized, pixelated SVG.
Why SVGs disappear or look wrong
| Symptom | Likely cause | Action |
|---|---|---|
| Completely blank SVG area | Unsupported <object> path, missing file permission, bad URL or zero dimensions |
Switch to <img> or inline SVG; add dimensions and --allow/--enable-local-file-access; verify paths |
| SVG itself appears but an embedded picture is missing | Nested external or data-image handling differs in the Qt WebKit build | Inline or preprocess the nested image; test a minimal SVG |
clip-path or opacity is ignored |
Feature coverage differs between patched and unpatched builds | Simplify the artwork or use a renderer with the required feature coverage |
| Text or shapes look jagged at 400% zoom | The SVG was rasterized during PDF generation | Inspect another build and test a maintained renderer when vector preservation is required |
| Works on one machine only | Different version, Qt patch status, OS, packaging or display server | Pin the binary and reproduce with the production environment |
Nested images inside SVG
Issue #2996 reports wkhtmltopdf 0.12.3 with patched Qt losing an image referenced inside an external SVG through <image xlink:href="data:image/jpeg;base64,...">, even though Firefox and Chrome displayed it. Inlining the SVG made images visible in that report but introduced other rendering errors. This is a compatibility case, not evidence that every 0.12.3 build fails; reproduce with your exact binary and simplify the SVG.
Rasterization and vector fidelity
Issue #4155, reported against wkhtmltopdf 0.12.5 with patched Qt, describes an SVG becoming rasterized in the PDF and appearing pixelated at 400% zoom. wkhtmltopdf does not promise that every SVG remains vector data in the resulting PDF. If selectable, infinitely scalable vector output is a requirement, evaluate a maintained renderer instead of searching for a flag that forces preservation.
Recommended Free Tools
Rank #4
- 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
Build-specific feature gaps
Issue #4611 (opened February 10, 2020) reports differences between patched and unpatched builds, including missing clip-path paths and ignored opacity; it also reports an Xvfb setup rasterizing <img> elements. Include build and display details in any bug report.
Reliability and production practices
- Pin versions. Save the executable version and package source in your build documentation.
- Keep a fixture suite. Include plain paths, text, gradients, opacity, clipping, external CSS, fonts and nested images.
- Compare PDFs, not browser screenshots. Check both visual appearance and zoom behavior.
- Fail loudly. Capture stderr and use load-error options so missing resources are actionable.
- Preprocess fragile assets. Converting complex SVG dependencies to self-contained markup can improve repeatability, but verify that it does not change layout.
- Plan an alternate renderer. The archived upstream project is not receiving fixes for newly encountered SVG or PDF limitations.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. Its capture pipeline accepts cookie and consent banners before removing more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers. For AI workflows, its MCP tools—take_screenshot, get_page_info and capture_pdf—work with Claude, Cursor and other MCP clients.
For a normal web page (replace the URL with the page that contains your SVG), make one request:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
See the ScreenshotNeo API documentation for capture options, including full-page shots, element selectors, custom CSS and JavaScript, waits, headers, cookies, user agents, PDF output and signed links. The same request in Python is:
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)
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}`);
The Free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 shots; every feature is on every plan. Sign up for ScreenshotNeo free.
Best Value
FAQ
Does wkhtmltopdf support SVG at all?
Yes, through Qt WebKit, but support depends on the exact build and the SVG features used.
Should I convert SVG to PNG first?
Only when your required features or vector fidelity are not reliable in your tested wkhtmltopdf build. Conversion removes SVG compatibility problems but also removes scalable vector data.
Why does a browser render the file while wkhtmltopdf does not?
Browsers and Qt WebKit differ in feature support, security defaults, resource loading and timing. Reproduce with a minimal HTML file and the production binary.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
What should I include in a bug report?
Include the SVG and HTML fixture, wkhtmltopdf version, patched or unpatched Qt status, operating system, package source, command line, local-file flags and display setup.
Frequently Asked Questions
Can I use remote SVG URLs?
Yes, provided the wkhtmltopdf process can resolve and load the URL; test network access and dependent resources in the same environment as production.
How do I know whether a PDF kept vectors?
Zoom far beyond normal reading size and inspect the PDF with a tool that can reveal image objects or paths; visible pixelation is a warning that rasterization occurred.
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.
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 →
