What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
On Debian Bookworm, install wkhtmltopdf from Debian’s repository with sudo apt update followed by sudo apt install wkhtmltopdf. Confirm the executable and version with command -v wkhtmltopdf and wkhtmltopdf --version. Bookworm currently lists version 0.12.6-2, while Bullseye lists 0.12.6-1, so always check the package available on the specific machine.
Install wkhtmltopdf from Debian’s repository
APT is the safest default because it selects the package built for your Debian release and installs its declared dependencies. Run these commands in a terminal or an SSH session:
sudo apt updatesudo apt install wkhtmltopdfcommand -v wkhtmltopdfwkhtmltopdf --version
The Debian Bookworm package record identifies wkhtmltopdf as a command-line HTML-to-PDF and image converter and lists version 0.12.6-2. The Bullseye package record lists 0.12.6-1. These versions are release-specific; the command output on your host is authoritative.
Check availability before installing
To see which candidate version APT offers, run:
apt-cache policy wkhtmltopdfLook at the Candidate line and the configured repository suites. If no candidate appears, confirm that the correct Debian repositories are enabled and that the machine is using a supported suite. Do not assume that a package available in Bookworm is present in every Debian suite: Debian’s package tracker records that wkhtmltopdf was removed from testing on 2025-02-05.
#1 Best Overall
Verify that conversion works
After installation, test both the binary and a conversion. A local file avoids network, TLS, and remote-page variables.
- Create a test document:
cat > test.html <<'EOF'
<!doctype html>
<html><head><meta charset="utf-8"><title>wkhtmltopdf test</title></head>
<body><h1>It works</h1><p>Generated on Debian.</p></body></html>
EOF- Convert it to PDF:
wkhtmltopdf test.html test.pdf- Check that the output exists and is a PDF:
ls -lh test.pdf
file test.pdfFor a trusted web page, use the same syntax with an HTTPS URL:
wkhtmltopdf https://example.com example.pdfNever feed untrusted HTML or URLs to a privileged conversion process without considering what the renderer can access. A page can contain JavaScript, external requests, or links to internal services.
Dependencies and the headless-server requirement
Debian’s package metadata declares Qt 5 components including Core, GUI, Network, Print Support, SVG, WebKit, and Widgets, along with standard C and C++ runtime libraries. APT normally installs these automatically. The same package record says an X11 server is required and lists xvfb as a possible virtual X server provider.
Install a virtual display when SSH or CI has no X server
On a minimal VPS, container, CI runner, or other machine without a desktop display, install Xvfb:
sudo apt update
sudo apt install xvfbRun wkhtmltopdf through a temporary virtual display:
xvfb-run --auto-servernum --server-args='-screen 0 1280x1024x24'
wkhtmltopdf https://example.com example.pdfThen inspect the exit status and output file:
echo $?
file example.pdfWhether a particular invocation works without Xvfb depends on the display libraries and environment already present. Treat the virtual display as a compatibility measure, not proof that Debian’s build is display-independent.
Diagnose display errors
- “Could not connect to display”: no usable X display is available. Use
xvfb-run, or configure the service’sDISPLAYcorrectly. - Conversion hangs: test a local HTML file, then add a controlled timeout at the service layer and inspect pages that wait indefinitely for scripts or network resources.
- Fonts or images are missing: install the fonts and resource packages your documents require, and verify that the conversion user can read them.
Debian’s build is not identical to every upstream build
The Debian package is not built against a forked version of Qt. As a result, options that depend on patched Qt are unsupported or behave differently. If your application depends on a particular wkhtmltopdf switch, verify it against the installed binary instead of assuming that an option documented for an upstream build is available.
Recommended Free Tools
List the options accepted by your installation:
wkhtmltopdf --extended-helpFor a quick check of one option:
wkhtmltopdf --help | grep -i 'option-name'Replace option-name with the switch your application needs. Test the exact page, CSS, JavaScript, fonts, and output mode used in production.
When an upstream .deb is appropriate
The official wkhtmltopdf packaging releases page provides Debian-specific artifacts, including a Bookworm 0.12.6.1-3 amd64 package dated 2023-05-21. That file is different from Debian Bookworm’s repository package 0.12.6-2.
Rank #3
Do not replace the repository package merely because the upstream version string is newer. Compare all of the following first:
- Exact Debian release and CPU architecture.
- Required Qt/WebKit capabilities, especially options relying on patched Qt.
- Dependencies and whether the package fits your system’s package-management and update process.
- Security status of the exact build you intend to deploy.
If you deliberately choose the upstream artifact, download it from the upstream page, inspect its architecture and dependencies, and install it only after testing in a staging environment. Keep a record of the package source so future administrators know which update path applies. For most Bookworm and Bullseye systems, Debian’s repository package remains the simpler starting point.
Free tools Windows power users keep installed
One-click scans. No signup required.
Security and operational precautions
The Debian Security Tracker lists CVE-2022-35583 as open and unimportant for Bookworm, lists CVE-2020-21365 as resolved, and records security announcement DLA-3158-1. Status can change, so check the tracker before deployment rather than describing any wkhtmltopdf build as vulnerability-free.
Reduce risk when rendering remote or supplied content
- Run conversions as a dedicated unprivileged user.
- Use network egress controls when the document does not need arbitrary outbound requests.
- Validate and constrain input URLs; do not allow users to target internal addresses or cloud metadata endpoints.
- Use a temporary working directory with suitable permissions and delete sensitive intermediate files.
- Apply process, memory, and wall-clock limits in the surrounding service.
- Patch Debian and its dependencies through the normal security-update process.
Common installation problems
APT cannot locate the package
Run sudo apt update, then apt-cache policy wkhtmltopdf. Check /etc/apt/sources.list and files under /etc/apt/sources.list.d/ for repositories matching the installed Debian suite. If the host tracks testing, remember that the tracker records wkhtmltopdf’s removal from testing on 2025-02-05; choose a supported package route rather than copying a random file from another release.
The command is installed but not found
Run command -v wkhtmltopdf and inspect the package contents:
dpkg -L wkhtmltopdf | grep '/wkhtmltopdf$'If the binary exists outside the service account’s PATH, use its absolute path or correct the service environment. Reinstalling without identifying the path problem usually does not fix it.
PDF output is blank or incomplete
First convert a simple local HTML file. If that works, the remote page may require JavaScript, authentication, a delay, accessible fonts, or resources blocked by the server. Capture diagnostics in a staging run and verify the installed build’s supported switches with wkhtmltopdf --extended-help.
Permission errors
Ensure the conversion user can read the input and write the destination directory. Avoid running the converter as root just to bypass a permissions problem; correct ownership and directory permissions instead.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your real goal is a clean screenshot rather than a Debian-managed wkhtmltopdf process, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF. Before capture it accepts consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup 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. Its MCP tools—take_screenshot, get_page_info, and capture_pdf—work with Claude, Cursor, and other MCP clients.
Use the same call from a shell:
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 authentication, output formats, and options. The API also supports full-page captures with lazy images loaded, CSS-selector element capture, dark mode, device presets, arbitrary viewports, retina scale, PDF paper and page-range controls, custom CSS or JavaScript, clicks before capture, selector hiding, waits for selectors or network idle, request and resource blocking, custom headers, cookies, user agents and Authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API, and an OpenAPI specification. Common parameter names used by other screenshot APIs also work.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Python and Node.js examples
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));Every feature is included on every plan: 1,000 shots per month are free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to get an API key.
FAQ
Which Debian version should I use?
Use the package matching the release already installed on the machine. Bookworm and Bullseye have different package versions, and testing has a different package state.
Does installing wkhtmltopdf install Xvfb automatically?
No. Debian declares an X11 requirement and lists Xvfb as a possible provider; install and invoke xvfb-run when your server has no display.
Can I assume upstream and Debian builds support the same switches?
No. Debian’s build is not based on forked Qt, so verify every option your workload requires against the installed executable.
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 errorsIs the Debian package vulnerability-free?
No such blanket claim is supported. Check the live Debian Security Tracker for the package and release you deploy.
The Bottom Line
For Bookworm or Bullseye, start with APT, verify the installed version and conversion, add Xvfb on display-less systems, and test any patched-Qt-dependent option before production. Choose an upstream .deb only after comparing compatibility, dependencies, maintenance, and security for the exact host.
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.
