There is no verified, universal one-line fix for every wkhtmltopdf “segmentation fault” on Alpine Linux. A signal-11 crash, a hang, a missing-library error and a Qt plugin startup failure have different causes. Before changing packages, record the exact image tag, Alpine release, CPU architecture, wkhtmltopdf version and build flavor, complete command, input document, exit code or signal, and stderr logs. Then isolate the failure systematically.
The underlying renderer is also obsolete: the wkhtmltopdf project status page states, “Qt 4 (which wkhtmltopdf uses) hasn’t been supported since 2015, the WebKit in it hasn’t been updated since 2012.” That age makes runtime compatibility and migration decisions as important as debugging one crash.
First establish what actually failed
Run the command inside the same container and save its diagnostics:
wkhtmltopdf -V
cat /etc/alpine-release
uname -m
wkhtmltopdf input.html output.pdf
printf 'exit=%sn' "$?"Capture the complete command, environment variables, stderr, container base-image digest, and whether the process exits immediately, hangs, or terminates with signal 11. “It crashed” is not precise enough to choose a repair. A timeout may be caused by a page waiting for JavaScript; an error such as “error while loading shared libraries” is a linker problem; a Qt platform-plugin message is a deployment problem.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →#1 Best Overall
Record the build provenance
Determine whether the executable came from Alpine’s repository, an upstream Linux package, a custom build, a patched-Qt build or a copied binary. Also record whether the image is x86_64, aarch64 or another architecture. A binary built for another distribution can fail because of libc, loader, architecture or library differences even when the file exists and is executable.
Build a minimal reproduction
Create a local document with no network, fonts, images or JavaScript:
cat > /tmp/minimal.html <<'EOF'
<!doctype html>
<html><body><h1>Test</h1><p>Local render.</p></body></html>
EOF
wkhtmltopdf /tmp/minimal.html /tmp/minimal.pdfIf this succeeds, add one variable at a time: local fonts, images, remote URLs, scripts, cookies and command-line options. Keep a known-good minimal file so you can tell whether a later change broke the renderer or merely exposed an input-specific defect.
Isolate options in small groups
Test the real command with layout options first, then JavaScript and waiting options, then headers, cookies and authentication. A report titled “wkhtmltopdf on alpine hangs forever when --window-status is provided” describes a hang, not a proven segmentation fault; the reporter said the sample ran after removing load.windowStatus/--window-status (issue #4026). Use that as a reason to isolate the option, not as a universal diagnosis.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #2
Inspect the executable and Qt runtime
Qt’s Linux deployment guidance explains that the dynamic linker must locate shared libraries and that Qt plugins must be installed where Qt can load them. It recommends using ldd to inspect shared dependencies (Qt Linux deployment documentation).
command -v wkhtmltopdf
readlink -f "$(command -v wkhtmltopdf)"
file "$(command -v wkhtmltopdf)"
ldd "$(command -v wkhtmltopdf)" | grep -i 'not found' || true
find /usr -type f ( -name 'libQt*.so*' -o -name 'libq*.so*' ) 2>/dev/null | head -100- “not found” libraries: inspect the package that should provide each library in the current Alpine branch; do not blindly install a similarly named package from an old tutorial.
- Architecture mismatch: use an executable and image with the same architecture, then rebuild or select a matching image.
- Plugin errors: verify the Qt platform, image-format and text plugins are present and discoverable. Check any
QT_PLUGIN_PATHor related environment override that may point to the wrong tree. - Unexpected libc or loader: do not assume a glibc-oriented package is safe on Alpine’s musl-based image. Use a build intended for the target runtime or move the renderer behind a compatible container boundary.
Qt also notes that a failed dlopen() can, in some circumstances, lead to an X11 library crash. That is a general Qt deployment warning, not proof that a particular wkhtmltopdf library is responsible; inspect the actual binary and libraries in your image.
Check Alpine package history and provenance
Historical package information explains why old fixes found online are unreliable. The Alpine v3.14 x86_64 index lists wkhtmltopdf 0.12.6-r0, built on 2020-06-11 (package index). Alpine 3.15 release notes say qt5-qtwebkit, kdewebkit, wkhtmltopdf and py3-pdfkit were removed because of known vulnerabilities and lack of upstream QtWebKit support (release notes).
Those dates establish historical context, not current availability. Check the official repository and security advisories for your exact Alpine branch before running apk add. Never mix repositories from different releases merely to obtain an old QtWebKit package.
Be cautious with patched-Qt recipes
A historical community recipe for Alpine 3.8/3.9 uses patched Qt and legacy OpenSSL (movio repository). It may document how an older image was assembled, but copying it into a current production image can create compatibility and security problems. Rebuild from reviewed sources, pin versions, scan the resulting image and document the provenance if you must reproduce that approach. A user request for a “Latest release of wkhtmltopdf patched with QT for Alpine Linux” (issue #4581) is a request for a download, not evidence that a maintained official Alpine build exists.
Try an isolated compatible container
If repairing the Alpine dependency graph costs more than the renderer is worth, run wkhtmltopdf in a separate image with its expected runtime libraries and expose a narrow rendering interface. The restruct wkhtmltopdf-static project documents a wkhtmltopdf 0.12.6 patched-Qt Docker image based on Ubuntu 22.04 with bundled runtime libraries. Treat it as an operational option to evaluate, not an official Alpine fix or a security endorsement.
Before adopting another image
- Verify current maintenance activity, image tags, architecture support and source/build provenance.
- Run it as a non-root user where possible, restrict outbound network access and sanitize untrusted HTML.
- Compare PDFs generated from representative documents, including fonts, headers, footers, JavaScript and remote assets.
- Review your organization’s vulnerability, licensing and base-image policy.
Decide whether to replace wkhtmltopdf
Alpine’s 3.15 notes call WeasyPrint the most direct replacement and also mention Puppeteer and Pandoc. None is automatically equivalent. Choose by testing your own documents against these axes:
| Requirement | Questions to test |
|---|---|
| Rendering fidelity | Do CSS layout, fonts, SVG, pagination and print styles match your required PDFs? |
| JavaScript | Does the document need a browser engine, or is static HTML sufficient? |
| Headers and footers | Are wkhtmltopdf-specific header/footer features required? |
| Runtime | Can the chosen engine run reliably on Alpine, or should it use a separate service? |
| Maintenance and security | Is the engine actively supported and patchable under your policy? |
| Operations | What memory, startup time, queueing and deployment work will your team own? |
The sources provide no benchmark ranking these alternatives. A representative test corpus, visual comparison and failure-rate measurement are more useful than a generic “fastest” claim.
Common symptoms and targeted fixes
Immediate signal-11 termination
Reproduce with the minimal file, confirm architecture and run ldd. If only the full document fails, add assets and options incrementally. If even the minimal file fails, prioritize binary, loader, Qt plugin and image compatibility over HTML debugging.
Hang or timeout
Remove waiting controls temporarily, especially --window-status, and test a local file. Check whether JavaScript waits for a status value that the page never sets. A hang is not evidence of a segmentation fault.
Missing shared library
Install the provider from the current branch only after identifying the exact missing soname, or use a build whose dependencies are bundled. Do not satisfy the message by copying arbitrary libraries from another distribution.
Qt platform-plugin or X11 error
Inspect plugin paths and required libraries inside the target image. Compare environment variables and filesystem layout with the build’s documented expectations. A plugin copied from a different Qt version can be incompatible.
Free tools Windows power users keep installed
One-click scans. No signup required.
Works locally, fails in CI
Compare image digest, architecture, fonts, locale, sandbox permissions, network policy and command-line arguments. Log wkhtmltopdf -V and ldd output in CI so a base-image change is visible.
Or skip the browser setup
If your actual goal is a website image rather than a PDF rendered by wkhtmltopdf, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; only clean shots are billed. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, and response headers identify the page verdict and billing status. AI agents can use its MCP tools—take_screenshot, get_page_info and capture_pdf—from Claude, Cursor or another MCP client.
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 API documentation for options such as full-page capture, CSS selectors, dark mode, device presets, retina scale, PDF paper and margins, custom CSS/JavaScript, waits, request blocking, headers, cookies, user agents, geolocation, transparent backgrounds, resizing, cache TTL, signed links, asynchronous webhooks, bulk capture and usage reporting. Every feature is included on every plan. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Python and Node.js equivalents
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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Frequently Asked Questions
Does installing a newer Alpine package guarantee that the segfault disappears?
No. Package availability and compatibility vary by branch, architecture and build flavor, and the documented evidence does not establish a universal trigger or repair.
Recommended Free Tools
Should I copy a wkhtmltopdf binary from Ubuntu into Alpine?
Usually not without validating its loader, libc, architecture and every shared Qt/plugin dependency. A compatible isolated container is safer to evaluate than an unverified cross-distribution copy.
When is ScreenshotNeo a better fit?
Use it when you need website screenshots or PDF capture through an API or MCP client rather than maintaining a legacy wkhtmltopdf runtime.
The Bottom Line
Diagnose the exact failure first, inspect the binary/runtime pair, and treat old Alpine recipes as historical. If the legacy stack remains fragile, isolate it in a reviewed compatible container or migrate after testing representative documents against your required output.
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.
