On Debian Bookworm, install wkhtmltopdf from Debian’s repositories with sudo apt update followed by sudo apt install wkhtmltopdf. Verify the executable with wkhtmltopdf --version, then test a conversion. The package is release-specific: Bookworm lists 0.12.6-2, while Bullseye lists 0.12.6-1, and Debian’s testing suite no longer contains the package according to the tracker entry dated 2025-02-05.
Check your Debian release before installing
Package versions and availability depend on the Debian suite and CPU architecture. Identify the system first:
cat /etc/os-release
dpkg --print-architecture
apt-cache policy wkhtmltopdfOn Bookworm, the repository record lists version 0.12.6-2. Bullseye lists 0.12.6-1. The policy command shows whether APT can see a candidate version in your configured repositories. If it reports no candidate, do not assume that another suite’s package is interchangeable; check the repositories and release-specific package information instead.
Install the Debian package
- Refresh package metadata.
sudo apt update - Install wkhtmltopdf.
sudo apt install wkhtmltopdf - Confirm that the command is on your PATH.
command -v wkhtmltopdf - Print the installed build.
wkhtmltopdf --version
APT is the safest default because it selects the package built for your Debian release and resolves its declared dependencies. The Bookworm package includes Qt 5 components such as Core, GUI, Network, Print Support, SVG, WebKit and Widgets, along with standard C and C++ runtime libraries. APT normally installs these automatically.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute#1 Best Overall
Run a first conversion
Convert a local HTML file
Create a minimal document:
cat > input.html <<'EOF'
<!doctype html>
<html><head><meta charset="utf-8"><title>Test</title></head>
<body><h1>wkhtmltopdf works</h1><p>Debian conversion test.</p></body></html>
EOF
wkhtmltopdf input.html output.pdf
file output.pdf
ls -lh output.pdfA successful run creates output.pdf. Open it on a workstation or inspect it with your normal PDF tools.
Convert a web URL
wkhtmltopdf https://example.com example.pdfOnly render URLs you trust. Remote pages can change, require JavaScript, block automated clients or reference resources that are unavailable from the server.
Render an image instead
The same executable can produce an image when the output extension identifies the format:
wkhtmltoimage https://example.com example.pngCheck that the companion command was installed with the package:
Free tools Windows power users keep installed
One-click scans. No signup required.
command -v wkhtmltoimage
wkhtmltoimage --versionUsing wkhtmltopdf on a headless Debian server
Debian’s package metadata declares an X11 server requirement and lists xvfb as a possible virtual X server provider. A machine without a desktop session may therefore need a display setup even though no monitor is attached. Whether a particular invocation works depends on the installed display environment; verify it rather than assuming headless support.
Install a virtual display provider
sudo apt update
sudo apt install xvfbRun the conversion through Xvfb
xvfb-run --auto-servernum --server-args='-screen 0 1280x1024x24'
wkhtmltopdf https://example.com example.pdfIf your service launches wkhtmltopdf, apply the same wrapper in the service command or start a managed virtual display and export its DISPLAY value. Test under the same user and environment as the service; a command that works in an interactive shell can fail when launched by a scheduler or system service.
What Debian’s build supports—and what it may not
The Debian package description states that it is not built against a forked Qt version. Some wkhtmltopdf options depend on features in patched Qt builds, so an option documented for an upstream package may be unsupported or behave differently in Debian’s build. Treat the installed binary as the authority:
wkhtmltopdf --extended-help
wkhtmltopdf --help | lessBefore deploying a workflow, test every option you rely on, including JavaScript execution, headers, cookies, custom styling, page breaks and local-file access. Do not infer support merely from an example written for a different distribution package.
Rank #3
Debian package versus an upstream .deb
| Factor | Debian repository package | Upstream distribution package |
|---|---|---|
| Default choice | Best first route for a matching Debian release | Use only for a documented requirement |
| Bookworm version cited | 0.12.6-2 | Upstream lists a Bookworm-specific 0.12.6.1-3 amd64 artifact dated 2023-05-21 |
| Dependency handling | APT resolves dependencies and tracks updates | You must verify release, architecture and library compatibility |
| Qt feature set | Debian’s non-forked-Qt build; some options may be unsupported | May provide capabilities absent from Debian’s build; verify the exact artifact |
| Maintenance fit | Integrated with Debian package management | Separate download and update process |
Do not mix an upstream package into a working Debian installation simply to obtain a newer-looking version. Compare the exact needed capability, architecture, dependencies and security status first. The available package information does not support a blanket claim that the upstream artifact is better.
Troubleshooting installation and conversion failures
“Unable to locate package”
- Run
sudo apt updateand read any repository errors. - Check
apt-cache policy wkhtmltopdfand your Debian release. - Confirm that repositories for the installed suite and architecture are enabled. Do not install a package from another suite without checking compatibility.
The command is missing after installation
Run dpkg -L wkhtmltopdf | grep '/wkhtmltopdf$' to locate the file, then check echo "$PATH". A service account can have a different PATH from your login shell; use the absolute path shown by command -v or the package listing.
“cannot connect to X server” or display errors
Install xvfb and retry with xvfb-run. If a virtual display already exists, verify DISPLAY, permissions and the service user. Capture the complete stderr output; it identifies whether the failure occurs before page loading.
Blank or incomplete output
- Confirm the URL is reachable from the server with the same DNS, proxy and firewall rules.
- Wait for client-side content when necessary, but remember that this older rendering engine may not support modern web APIs.
- Test local assets and relative URLs. A page that relies on blocked mixed content, authentication or inaccessible file paths can render blank.
- Compare a minimal local document with the failing page to separate installation problems from page-specific behavior.
An option is reported as unknown
Inspect wkhtmltopdf --extended-help. The Debian build is not the patched-Qt build, so an upstream-only option may not exist. Redesign the command around supported options or evaluate an explicitly compatible package after checking its dependencies and security status.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated 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 matchPermission or output-path errors
Write to a directory where the invoking user has permission, and ensure the destination does not already belong to another account. For automated jobs, use an absolute output path and create it with appropriate ownership before invoking wkhtmltopdf.
Security and operational considerations
The Debian Security Tracker records CVE-2022-35583 as an open, unimportant issue for Bookworm, CVE-2020-21365 as resolved, and security announcement DLA-3158-1. Status can change, so check the live tracker and the package’s security information before deployment. This is not a basis for calling every installation unsafe, but it is a reason to keep the system updated and review exposure.
- Do not render untrusted URLs or HTML in a privileged process.
- Run conversions as a dedicated, least-privileged user and restrict filesystem access.
- Control outbound network access if documents do not need to fetch arbitrary resources.
- Set job timeouts outside wkhtmltopdf so a stalled page cannot consume workers indefinitely.
- Record the binary version, Debian release, command-line options and exit status for reproducibility.
Performance and reliability checklist
- Reuse a prepared worker environment rather than reinstalling dependencies per job.
- Use local assets where possible to reduce DNS, TLS and third-party script delays.
- Measure conversion time with representative pages; JavaScript-heavy sites can vary substantially.
- Retry transient network failures at the job layer, but cap retries and preserve the original stderr.
- Validate that the resulting PDF exists, is non-empty and opens before marking a job successful.
Or skip the browser setup
If your goal is a clean screenshot or PDF rather than maintaining a local rendering stack, ScreenshotNeo provides a website screenshot API. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the page verdict and billing status in headers.
One call returns PNG, JPEG, WebP or PDF:
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 options such as full-page lazy-image loading, CSS-selector element capture, device and viewport settings, custom CSS or JavaScript, waits, request blocking, headers, cookies, geolocation, PDF page ranges, caching, signed links, asynchronous webhooks and bulk capture. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →The Free plan includes 1,000 screenshots per month without a card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Sign up for ScreenshotNeo and make your first capture without installing a browser stack.
FAQ
Can I install wkhtmltopdf with Snap or Flatpak instead?
This guide covers Debian’s APT package and the documented upstream Debian artifact. Use a packaging route that matches your deployment policy and verify its executable, dependencies and security update path.
Does wkhtmltopdf replace a modern browser?
No. It uses its own Qt/WebKit rendering stack. Modern CSS or JavaScript may require a different renderer, and Debian’s non-forked-Qt build can omit options expected by some upstream documentation.
Why does my version differ from a tutorial?
Tutorials may target another Debian release, an upstream artifact or an older repository snapshot. Compare apt-cache policy wkhtmltopdf, your release and architecture before changing packages.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
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.
