The most reliable fix for blurry or clipped charts in wkhtmltopdf is to export the chart as SVG, give it explicit dimensions, control wkhtmltopdf’s scaling, and wait for JavaScript and assets to finish before conversion. Then validate the PDF at 100% and at its intended print size. PNG can work, but only when its pixel dimensions match the final physical size.
What wkhtmltopdf is—and why charts suffer
wkhtmltopdf is an open-source (LGPLv3) command-line tool that renders HTML to PDF with a bundled or linked Qt WebKit engine. It is not a current browser UI, so chart behavior depends on the older WebKit implementation and on conversion flags. The manual describes it as converting HTML pages “using wkhtmltopdf patched qt.”
Common symptoms have different causes:
- Blurred lines or text: a small raster image was enlarged, or the page was resampled by smart shrinking.
- Clipped labels: the chart or its parent has no explicit width, the page is too narrow, or a page break intersects the drawing.
- Missing chart: JavaScript, data, fonts, or images were not ready or could not be loaded.
- Unexpected colors or layout: print media CSS was not selected, or the chart relies on browser features WebKit does not support.
The sequence below addresses quality in that order: representation, dimensions, scaling, readiness, CSS, assets, and validation.
1. Use SVG whenever the chart library supports it
SVG stores text, lines, markers, and curves as geometry. It therefore remains sharp when a PDF is zoomed or printed, unlike a small PNG that must be enlarged. Configure the chart library to emit inline SVG or an SVG file, and make sure wkhtmltopdf can read it.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
SVG is an engineering preference, not a guarantee that every modern SVG feature works in Qt WebKit. Test gradients, masks, embedded fonts, filters, and complex text layout; simplify those features if they render incorrectly. Keep essential labels as ordinary SVG text rather than converting everything to a bitmap.
When PNG is the practical choice
Use PNG when the library has no usable SVG export, when a chart contains effects that this WebKit build cannot reproduce, or when a fixed bitmap is required. Export at the final physical size multiplied by the intended print density. Do not export a 400-pixel image and place it into a 1,200-pixel box. Avoid repeatedly resizing the same file.
2. Set chart and page dimensions explicitly
Give the chart, its wrapper, and (for SVG) the width and height attributes explicit values. Use CSS pixels that fit inside the printable page after margins. For a wide chart, choose landscape orientation rather than forcing a portrait page to shrink it.
wkhtmltopdf --page-size A4 --orientation Landscape
--margin-top 12mm --margin-right 12mm
--margin-bottom 12mm --margin-left 12mm
report.html report.pdfAlternatively specify --page-width and --page-height when a custom paper size is required. Reserve space for legends, axis titles, and long tick labels; a chart that exactly touches its container is likely to be clipped after conversion.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Prevent page-break damage
@media print {
.chart { width: 100%; break-inside: avoid; page-break-inside: avoid; }
.chart svg { display: block; width: 100%; height: auto; }
.chart-title, .legend { font-size: 11pt; }
}If a chart is taller than the remaining page, put it on a new page instead of relying on an automatic split. A split can separate the plot from its legend or cut off the bottom axis.
3. Make scaling predictable
wkhtmltopdf documents --zoom (default 1), --viewport-size, and --disable-smart-shrinking. Smart shrinking fits content automatically, but the manual notes that it makes the pixel/dpi ratio non-constant. That can turn carefully chosen CSS dimensions into inconsistent output.
Rank #2
wkhtmltopdf --viewport-size 1280x900
--zoom 1 --disable-smart-shrinking
--page-size A4 --orientation Landscape
report.html report.pdfDisabling smart shrinking is useful when CSS pixels must map predictably to the page, but it is not a universal “quality” switch. You must then choose a page width, margins, viewport, and chart width that actually fit. If content is clipped, increase the page width, reduce margins, or reduce the chart’s CSS width instead of repeatedly increasing zoom.
The manual lists a default --dpi of 96. This affects CSS-to-physical-size interpretation; it does not turn a low-resolution PNG into a detailed image.
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 match4. Wait for JavaScript charts deterministically
JavaScript is enabled by default, and the documented --javascript-delay default is 200 ms. That is often too short for data fetches, font loading, and chart animation.
Simple delay
wkhtmltopdf --javascript-delay 1500
--page-size A4 --orientation Landscape
report.html report.pdfIncrease the delay only enough for the slowest normal render. A very large fixed delay makes every job slower and still fails when network timing varies.
Window-status synchronization
A page can set a known status after data, fonts, and drawing are complete:
<script>
window.status = 'chart-loading';
async function drawReport() {
await loadData();
await document.fonts.ready;
renderChart();
requestAnimationFrame(() => { window.status = 'chart-ready'; });
}
drawReport();
</script>wkhtmltopdf --window-status chart-ready
--page-size A4 report.html report.pdfThis is more deterministic than guessing a delay. Ensure every failure path sets an alternate status or exits visibly; otherwise a broken request can leave conversion waiting indefinitely.
Recommended Free Tools
5. Use print CSS intentionally
Screen media is the default. Add --print-media-type when the PDF needs its own dimensions, colors, visibility rules, or label sizes.
wkhtmltopdf --print-media-type
--page-size A4 --orientation Landscape
report.html report.pdfKeep the print stylesheet focused: set a stable chart width, hide interactive controls, increase small tick labels, and choose colors with enough contrast for grayscale printing. If the browser view looks correct but the PDF does not, inspect the computed styles under print media rather than changing the chart data.
6. Tune raster images without destroying detail
The manual documents --image-dpi with a default of 600 and --image-quality with a default of 94. These settings affect image handling and JPEG quality; they cannot restore detail that was absent from the source.
wkhtmltopdf --image-dpi 600 --image-quality 94
report.html report.pdfKeep the source PNG or JPEG large enough for its final printed dimensions, use PNG for sharp line art and text, and avoid --lowquality when labels matter. For photographs embedded beside a chart, JPEG may be smaller, but it is usually a poor choice for thin lines and small text.
7. Verify every dependency can load
Charts frequently depend on a JavaScript bundle, JSON data, web fonts, icons, and background images. Confirm that each URL is reachable from the conversion host, not merely from your desktop browser. Review wkhtmltopdf’s conversion output for failed resources.
For local files, explicitly review the security settings. Depending on the build and invocation, you may need --enable-local-file-access or narrowly scoped --allow paths:
Rank #4
- Funny saying for any front-end developer, web developer, computer programmer, computer systems engineer, mobile app developer, software developer, or code lover who likes to code, make funny programming jokes, and take memorable photos.
- Wear it proudly at International Programmers' Day, school, coding classes, or coding communities! It also makes a funny present for a computer programming lover friend.
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
wkhtmltopdf --enable-local-file-access
--allow /srv/report-assets
report.html report.pdfPrefer a local, versioned asset bundle for repeatable reports. If you must use network assets, provide stable URLs and account for authentication, redirects, and TLS compatibility. A missing font can change label widths enough to cause clipping even when the chart itself loaded.
8. Validate the result at its intended size
Open the PDF at 100% zoom, not only in a thumbnail. Print a representative page at the size your readers will use. Check:
- thin lines, point markers, and grid lines;
- tick labels, axis titles, legends, and units;
- color contrast in color and grayscale;
- the right and bottom edges for clipping;
- page breaks and chart-to-legend relationships;
- font substitution and missing glyphs.
The Qt documentation distinguishes QPrinter::ScreenResolution from HighResolution and says screen resolution is lower quality and intended only for drafts. That setting is relevant when another Qt-based stage creates or rasterizes content; it does not replace SVG or correct an undersized source bitmap.
Reusable command profiles
Stable, print-oriented SVG report
wkhtmltopdf --print-media-type --viewport-size 1280x900
--zoom 1 --disable-smart-shrinking
--javascript-delay 800
--page-size A4 --orientation Landscape
--margin-top 12mm --margin-right 12mm
--margin-bottom 12mm --margin-left 12mm
report.html report.pdfDeterministic asynchronous report
wkhtmltopdf --print-media-type --window-status chart-ready
--viewport-size 1280x900 --disable-smart-shrinking
--page-size A4 --orientation Landscape
report.html report.pdfStart with one profile, then change one variable at a time. Record the wkhtmltopdf version, page settings, chart dimensions, and asset versions so a later upgrade can be compared.
Common failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Everything is blurry | Small raster source or smart shrinking | Use SVG; otherwise export more pixels, set dimensions, and test --disable-smart-shrinking. |
| Only labels are clipped | Container too narrow, print CSS, or font substitution | Increase width/margins, set print font sizes, verify fonts load, and reserve legend space. |
| Blank chart | JavaScript or data was not ready | Use --window-status or a measured delay; inspect network and console-related conversion output. |
| Local images missing | Local-file access blocked | Use --enable-local-file-access and a narrow --allow directory. |
| Colors differ from browser | Print media rules or unsupported WebKit CSS | Use --print-media-type deliberately and simplify unsupported effects. |
| Chart split across pages | Insufficient remaining page height | Use break-inside: avoid, move the chart to a new page, or reduce its height. |
Performance, reliability, and when to migrate
SVG and local assets reduce repeated image decoding, while an excessive JavaScript delay increases every job’s latency. Window-status synchronization usually gives better throughput because fast pages finish quickly, but it requires reliable success and failure signaling. Disable animations in print CSS or chart configuration so the captured frame is stable.
wkhtmltopdf is a deliberate compatibility choice when changing infrastructure is risky. If your design depends on modern CSS, complex SVG filters, variable fonts, or browser APIs that Qt WebKit does not support, migration to a newer rendering engine may be more predictable than accumulating flags. Compare a representative set of charts, not a single page, before switching.
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
- Programming Language Lover Code Apparel. App or Web Design and Development Expert Funny Dress. Best Valentines Idea For Coding Lover. HTML Code or Meaning Costume
- Funny I Know HTML - How To Meet Ladies Computer Programmer Quotes
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Or skip the browser setup
If your real requirement is a clean capture of a finished web page rather than control over wkhtmltopdf internals, ScreenshotNeo provides a one-request screenshot or PDF API. Its cleanup step accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be disabled. Bot checks/CAPTCHAs, 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. It also offers an MCP server for Claude, Cursor, and other MCP clients.
See the ScreenshotNeo documentation for options such as full-page capture with lazy images loaded, CSS-selector element capture, device presets, retina scale, PDF paper size and margins, custom CSS/JavaScript, waits, request blocking, cookies and headers, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, and usage reporting.
cURL
curl -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)
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}`);The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000, and every feature is included on every plan. Sign up for the free plan.
FAQ
Does increasing --dpi fix a blurry SVG?
No. SVG is resolution-independent; blur usually comes from raster inputs, scaling, or a later rasterization step. Set dimensions and control shrinking first.
Should I always disable smart shrinking?
No. Disable it when predictable CSS-pixel sizing matters and you can size the page correctly. Leave it enabled when automatic fitting is more important than exact mapping, then verify labels and line weights.
Why does a chart work interactively but fail in the PDF?
The conversion process may finish before asynchronous data, fonts, or drawing complete, or a dependency may be inaccessible from the conversion host. Use a readiness status and inspect asset loading.
Frequently Asked Questions
Can I combine a fixed delay with window status?
Yes, but treat the status as the completion signal. A delay can be a fallback for animation or font settling; it should not be the only readiness test for data-driven charts.
What should I compare after changing wkhtmltopdf versions?
Compare the same HTML, assets, page dimensions, fonts, and command flags, then inspect chart geometry, labels, colors, and page breaks at 100%.
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 →The Bottom Line
For the sharpest wkhtmltopdf charts, start with SVG, explicit dimensions, intentional print CSS, deterministic JavaScript readiness, and predictable scaling. Use high-resolution raster sources only when SVG is unsuitable, and validate the actual PDF where it will be viewed or printed.
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.
