How to Download and Install wkhtmltopdf
Download wkhtmltopdf 0.12.6, install it on Windows, macOS, Debian, Ubuntu and other Linux systems, then verify and troubleshoot it safely.
Direct answer: Download wkhtmltopdf from the project’s official downloads page, choose the package matching your operating system and CPU architecture, install it, open a new terminal, and run wkhtmltopdf --version. The stable series is 0.12.6, released June 11, 2020. Then run a small conversion such as wkhtmltopdf https://example.com output.pdf to confirm that rendering works.
1. What wkhtmltopdf is
wkhtmltopdf is an open-source LGPLv3 command-line program that renders a URL, local HTML file or standard input to PDF. Its companion, wkhtmltoimage, renders HTML to image formats using Qt WebKit. The main project repository is archived, so 0.12.6 remains the stable series described by the project.
2. Choose the right download
Use the official wkhtmltopdf downloads page. All project downloads are hosted through GitHub releases. Select a row that matches both your operating system and architecture.
| System | Package to select | Important check |
|---|---|---|
| Windows | 32-bit or 64-bit installer or 7z archive | Choose the architecture used by your Windows installation. |
| macOS | Listed 64-bit installer for macOS 10.7 or later | Confirm that your macOS version is supported by the listed installer. |
| Debian or Ubuntu | Distribution package when available, otherwise the matching project package | Match the package to the exact distribution release and architecture. |
| AlmaLinux, CentOS, Amazon Linux, openSUSE or Arch Linux | The distribution-specific package listed by the project | Do not assume that a generic Linux binary works on every distribution. |
Distribution-specific builds exist because libraries, font configuration and libc behavior vary. Also check whether a build includes the project’s patched Qt features. Runtime components such as fonts and, for some Linux packages, X11 can affect whether conversion starts and whether output matches another machine.
3. Install on Windows
- Download the 32-bit or 64-bit installer from the official downloads page. The Windows installers support Vista or later according to the project matrix.
- Run the installer and accept the proposed installation location, or choose a controlled directory used by your deployment process.
- Finish setup and open a new Command Prompt or PowerShell window so the updated PATH is loaded.
- Verify the executable:
wkhtmltopdf --version - Run a smoke conversion:
wkhtmltopdf https://example.com output.pdf
If Windows reports that the command is not recognized, reopen the terminal first. If it still fails, invoke wkhtmltopdf.exe with its full installation path and add that directory to PATH for future shells.
4. Install on macOS
- Download the listed 64-bit installer for macOS 10.7 or later.
- Complete the installer.
- Open Terminal and verify the version:
wkhtmltopdf --version - Convert a public page to check that the executable can create a PDF:
wkhtmltopdf https://example.com output.pdf
If the shell cannot find the command, locate the installed executable and call it by its full path. Add that directory to your shell PATH after confirming the binary runs.
5. Install on Debian or Ubuntu
Prefer a package built for your distribution release. Debian Bookworm currently lists wkhtmltopdf 0.12.6-2+b1 for multiple architectures. A package-manager installation supplies the libraries expected by that distribution.
sudo apt update
sudo apt install wkhtmltopdf
wkhtmltopdf --version
wkhtmltopdf https://example.com output.pdfIf your release does not provide a suitable package, download the matching Debian or Ubuntu package from the project downloads matrix. Do not substitute a package for a different release simply because the CPU architecture matches.
6. Install on other Linux distributions
The project lists packages for AlmaLinux, CentOS, Amazon Linux, openSUSE and Arch Linux. Select the package for the exact distribution and architecture, install it using that distribution’s normal package workflow, then run:
wkhtmltopdf --version
wkhtmltopdf https://example.com output.pdfSome environments cannot install a package directly but can extract it. The official FAQ notes that extraction is possible when installation is unavailable; all required dependencies must still be present. Missing libraries, fonts or X11-related components can prevent startup or change the resulting PDF.
7. Verify the installation
- Check that the command resolves:
wkhtmltopdf --version. - Confirm that the reported version is the one you intended to deploy, normally 0.12.6 for the stable project series.
- Convert a harmless public page:
wkhtmltopdf https://example.com output.pdf. - Open the PDF and check that it is non-empty and readable.
- For an image conversion, use the companion executable:
wkhtmltoimage https://example.com output.png.
Keep the operating system, package source, architecture and version in your deployment notes. These details explain many differences between developer machines and production hosts.
8. Compatibility decisions that affect output
Operating system and CPU architecture
A package built for another architecture may fail immediately or require emulation. Always match the download row to the host architecture.
Patched Qt versus distribution builds
Project packages and distribution packages can differ in patched Qt features. If two systems produce different pagination, fonts or layout, first compare the exact package and version rather than changing the HTML.
Fonts and runtime libraries
Font configuration and libraries are part of rendering. A minimal server image may lack fonts available on a desktop, producing different line breaks or blank-looking output.
X11-related requirements
Debian package metadata lists Qt WebKit, Qt GUI, networking and print-support dependencies, together with X11-related components. If a Linux process exits before writing a PDF, inspect these dependencies before debugging the page itself.
9. Security: never pass untrusted HTML directly
The project’s downloads and FAQ warn: Do not use wkhtmltopdf with any untrusted HTML
; sanitize user-supplied HTML and JavaScript because unsafe input can lead to complete server takeover. Treat downloaded binaries and third-party mirrors cautiously, prefer the official project or your distribution repository, and verify checksums or signatures when a release asset provides them.
For a server-side service, isolate the converter, restrict outbound access where practical, set resource and process limits, and keep arbitrary user HTML away from a privileged host process. Sanitizing input is still required even inside a container.
10. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
command not found or “not recognized” |
The terminal started before installation, or the executable directory is absent from PATH. | Open a new terminal, inspect PATH, or run the executable by its full path. |
| Installer refuses to run | Wrong operating system or CPU architecture. | Return to the downloads matrix and select the matching row. |
| Linux binary fails to start | Missing libraries, fonts or X11-related runtime components. | Use the package built for the exact distribution release and install its dependencies. |
| Package cannot be installed | The environment does not support that package format or lacks permissions. | Use the distribution package, or extract the project package only after providing every required dependency. |
| Output differs between hosts | Different builds, patched Qt behavior, fonts or library versions. | Compare package source, version, architecture, fonts and runtime libraries. |
| PDF is empty or conversion exits early | The page did not load, or the runtime is incomplete. | Test https://example.com, check stderr, then inspect dependencies and network access. |
| Security review blocks deployment | Untrusted HTML or JavaScript is reaching the converter. | Sanitize input and isolate the process; never expose a privileged converter to arbitrary HTML. |
11. Performance, reliability and cost notes
- Performance: Rendering time depends on page size, network access, fonts and the host’s available CPU and memory. Reproduce production conditions when comparing timings.
- Reliability: Pin the package version and operating system image. Record the architecture and dependency set so upgrades are deliberate.
- Operations: Run a smoke conversion after installation and after every image or package change.
- Cost: wkhtmltopdf is open-source LGPLv3 software, so there is no license fee for the tool itself. Your infrastructure, maintenance and isolation still have operational cost.
12. Or skip the browser setup
If you need a clean screenshot or PDF without installing a local browser-rendering stack, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF.
Cookie and consent banners are accepted and removed before capture, along with more than 60 known consent platforms, newsletter popups and chat widgets. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed; response headers identify the page verdict and whether the request was billed. An MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.
See the ScreenshotNeo documentation for the full option set, including full-page capture with lazy-image loading, CSS-selector element capture, dark mode, device presets, retina scale, PDF paper and margin settings, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous jobs, webhooks, bulk capture and usage data.
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 each month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
13. FAQ
Which wkhtmltopdf version should I install?
Use the stable 0.12.6 series and choose a package matching your operating system, architecture and distribution.
Can I use a generic Linux binary?
It may fail because libraries, libc, fonts and Qt behavior vary. Prefer a package built for your exact distribution release.
How do I know installation succeeded?
Run wkhtmltopdf --version, then convert https://example.com and open the resulting PDF.
Is wkhtmltopdf safe for customer-provided HTML?
Not without sanitization and isolation. The project warns that untrusted HTML or JavaScript can take over the server running the converter.
Why does the same page look different on two machines?
Compare package builds, patched Qt features, fonts, runtime libraries and operating system versions.
