A wkhtmltopdf segmentation fault is a crash in the native wkhtmltopdf process, not a normal Python exception. The fastest reliable fix is to reproduce the exact command outside Python, identify the binary and build family, reduce the document to a minimal case, and then replace an incompatible or unmaintained build. Python’s pdfkit wrapper can expose the failing command, but it cannot repair a crash inside Qt/WebKit.
What the error actually means
When pdfkit.from_string(), from_file() or from_url() reports “Command failed” with “Segmentation fault”, the child process accessed invalid native memory and exited. The traceback is therefore a report from Python about a dead subprocess. Treat the renderer, its Qt/WebKit libraries, the input document and the execution environment as the likely fault domain.
wkhtmltopdf’s current stable series is 0.12.6, released June 11, 2020. Its Qt 4 base has been unsupported since 2015, and the embedded WebKit has not been updated since 2012. Those dates matter when modern JavaScript, fonts, CSS or operating-system libraries meet an old renderer.
1. Capture the exact failure from pdfkit
Install the wrapper and create a deliberately verbose test. The verbose=True option preserves renderer diagnostics instead of hiding them.
#1 Best Overall
import pdfkit
config = pdfkit.configuration(wkhtmltopdf="/opt/bin/wkhtmltopdf")
html = "<html><body><h1>Minimal test</h1></body></html>"
pdfkit.from_string(
html,
"out.pdf",
configuration=config,
verbose=True,
)If wkhtmltopdf is on PATH, omit configuration. For diagnosis, an explicit path is safer because it prevents a service, shell and development machine from silently selecting different binaries.
To inspect the command that pdfkit constructs, create a PDFKit object and print it:
import pdfkit
config = pdfkit.configuration(wkhtmltopdf="/opt/bin/wkhtmltopdf")
r = pdfkit.PDFKit(
"<h1>Minimal test</h1>",
"string",
configuration=config,
options={"quiet": False},
)
print(" ".join(r.command()))Record the Python version, operating system and architecture, binary path, complete command, stderr, exit code, and whether the input came from a string, file or URL. Do not discard stderr: warnings immediately before the crash often identify a problematic image, script, font or page.
2. Run the generated command without Python
Copy the printed command into a shell and run it unchanged. If it segfaults there too, Python is only the caller. Investigate the binary, Qt/WebKit runtime, input or resource loading. If it succeeds outside Python, compare the working directory, environment variables, permissions, temporary directory and the exact arguments supplied by your application.
Save the shell result, including its numeric exit status:
/opt/bin/wkhtmltopdf --version
/opt/bin/wkhtmltopdf input.html output.pdf
printf 'exit=%sn' "$?"A normal segmentation fault commonly produces exit status 139 (128 plus signal 11), although wrappers may format the message differently. The important evidence is the native process’s stderr and the binary identity, not the wording of the Python exception.
3. Verify which wkhtmltopdf build you are using
Pin the executable
pdfkit searches PATH by default and accepts an explicit executable through pdfkit.configuration(wkhtmltopdf=...). Use an absolute path in production and log <binary> --version during deployment. This catches a common failure mode: a laptop uses an official static package while a container or server resolves a distribution package with different patches and libraries.
Distinguish patched Qt from an unpatched distribution build
Debian and Ubuntu packages may be compiled without wkhtmltopdf’s Qt patches. Features such as outlines, headers, footers and tables of contents can then be absent or behave differently from the documentation. If your workload needs those features, install an official static package matched to the operating system and CPU architecture instead of mixing an unpatched binary with patched-Qt expectations.
Do not copy a binary built for another distribution merely because its filename looks right. Library combinations vary between distributions; an OS-matched package gives you a reproducible compatibility target. After replacing it, rerun the minimal test and the exact failing document.
4. Reduce the document until the crash has a trigger
- Create a local HTML file containing only plain text and a basic heading.
- Add your stylesheet, then fonts, images, SVG, JavaScript, headers, footers and table-of-contents options one at a time.
- When the crash returns, keep the smallest file and resource set that reproduces it.
- Run that reduced case directly with the pinned binary and preserve stderr.
This process separates a renderer defect from a specific asset or script. Large images, animated content, complex SVG, remote JavaScript and very large documents increase native memory pressure. A rendering process can emit warnings and then segfault; suppressing those warnings removes your best clue.
For remote pages, test a downloaded local copy. A changing server response, blocked request, cookie challenge or slow third-party asset can make an apparently random crash deterministic. Then reintroduce network resources selectively.
5. Check display and headless execution separately
wkhtmltopdf is designed for headless operation. You do not normally need a desktop session or xvfb. If the direct command reports an X-server or display error, use the virtual-display setup supported by your platform and keep that change separate from segfault diagnosis:
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC 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 & 11xvfb-run -a /opt/bin/wkhtmltopdf input.html output.pdfA virtual display can fix a missing-display error; it does not repair a native memory crash. First establish whether the unwrapped binary segfaults with a minimal local file. Then address display requirements only if stderr explicitly asks for them.
6. Control resource and security variables
- Disable or remove remote JavaScript, advertisements, trackers and third-party widgets while isolating the fault.
- Replace large raster images with small local files and simplify SVG.
- Test without headers, footers, outlines and TOC, then add each option back.
- Use a bounded input size and a process timeout in the Python service so a hung renderer cannot consume workers indefinitely.
- Run untrusted HTML in an isolated account or container. Network access and local-file access should be restricted according to your application’s threat model.
These controls do not make old WebKit current; they make failures reproducible and limit their impact.
7. Common symptoms and fixes
| Symptom | Likely cause | Action |
|---|---|---|
| Segfault occurs with a one-line local HTML file | Wrong, damaged or incompatible binary/runtime | Check --version, pin an OS-matched official build, and test again. |
| Only headers, footers, outlines or TOC trigger it | Unpatched distribution Qt or a feature-specific renderer bug | Use a patched-Qt build when those features are required; otherwise remove the option. |
| Only one image, SVG or font triggers it | Renderer bug or malformed/large asset | Replace or simplify the asset and retain the smallest reproducer. |
| Only remote URLs fail | Network timing, blocked resources, JavaScript or server response changes | Download locally, disable scripts, and add resources back incrementally. |
| “Could not connect to display” rather than segfault | Missing display environment | Use the supported virtual display setup; do not assume it fixes a segfault. |
| Works on a workstation but not in CI | Different PATH, architecture, libraries, permissions or temporary directory | Log all versions and paths, pin the executable, and reproduce inside the CI image. |
8. Produce a useful bug report
For a project issue, include the wkhtmltopdf version, operating-system version and a detailed reproducible HTML/CSS/JavaScript test case. Add the complete command, stderr, exit code, architecture and whether the crash occurs with a local file or URL. A minimal attachment is more actionable than an entire application repository.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.9. Know when to migrate
If the pinned binary still crashes on a minimal, reproducible workload, or cannot render the CSS and JavaScript your application requires, changing Python options is unlikely to make it dependable. The project distinguishes use cases: WeasyPrint is suited to controlled report generation, Prince is a commercial report renderer, and Puppeteer is aimed at JavaScript-heavy sites. Compare JavaScript execution, CSS fidelity, deployment footprint, security isolation, maintenance status, licensing cost and reproducibility in your CI or container before choosing.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Migration is especially sensible when you need a maintained browser engine. wkhtmltopdf’s old Qt/WebKit stack cannot acquire modern browser fixes simply by adding xvfb or increasing a timeout.
Or skip the browser setup
If your real goal is a clean image or PDF of a web page rather than a legacy HTML-to-PDF pipeline, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF. Cookie and consent banners, newsletter popups and chat widgets are removed before capture; bot checks, blank pages, failed loads and cache hits are not billed, and response headers report the page verdict and billing status.
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}`);See the ScreenshotNeo documentation for options such as full-page capture, CSS selectors, device presets, custom JavaScript, waits, blocking rules, PDFs, signed links, webhooks and bulk capture. Its MCP server lets Claude, Cursor and other MCP clients 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. Sign up free.
Frequently Asked Questions
Do I always need xvfb for wkhtmltopdf?
No. wkhtmltopdf is designed to run headlessly. Use a virtual display only when the direct command reports a display or X-server error; it does not generally fix a segmentation fault.
Why does pdfkit hide the useful error?
The wrapper reports that the child command failed. Enable verbose output, print the PDFKit command, and run that command directly so native stderr and the exit status are visible.
Which version should I pin?
The project lists 0.12.6 as the stable series, released June 11, 2020. Pin an OS- and architecture-matched build and record its full version output.
The Bottom Line
Diagnose the native process first: print pdfkit’s command, run it outside Python, verify the exact binary and patched-Qt expectations, then minimize the input while preserving stderr. If the old Qt/WebKit renderer remains unstable or cannot handle the workload, migrate to a maintained engine rather than treating xvfb as a universal fix.
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.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errors
