How to Install wkhtmltopdf on Windows

Quick answer: Download the stable Windows 0.12.6 build from the official wkhtmltopdf downloads page, run the Vista-or-later installer, enable the PATH option if offered, open a new PowerShell or Command Prompt window, and verify with wkhtmltopdf --version. Then create a test PDF with wkhtmltopdf https://example.com example.pdf.

wkhtmltopdf is a headless command-line utility that renders HTML into PDF with Qt WebKit. It runs without a display service. The project’s stable Windows series is 0.12.6, released June 11, 2020. The project repository was archived on January 2, 2023, so record the exact binary version in deployment documentation.

1. Choose the Windows download

Use the official project download page rather than an unofficial mirror. Under Windows, you will find:

Download	Best for	PATH setup	Portability
Installer (Vista or later)	Most desktop and server installations	May offer automatic PATH configuration	Installed application
64-bit 7z archive	Manual or portable deployments on 64-bit Windows	Manual	High
32-bit 7z archive	32-bit Windows environments	Manual	High

Match the archive architecture to the Windows environment. The installer is the simplest route. Choose an archive when you cannot run an installer, need a pinned directory, or want to copy the tool between machines.

2. Install with the Windows installer

Open the official downloads page.
In the Windows section, download the installer for Vista or later and the appropriate architecture.
Run the downloaded executable. Approve the Windows permission prompt if one appears.
Accept the license agreement.
Keep the wkhtmltopdf component selected. If the wizard offers to add it to PATH, enable that option.
Finish the wizard.
Close existing terminals and open a new PowerShell or Command Prompt window. A terminal opened before installation may not have the updated PATH.

3. Install from a 7z archive

The official page also publishes 32-bit and 64-bit 7z archives. Extract the selected archive to a stable directory such as C:\Program Files\wkhtmltopdf or an administrator-approved application directory. The archive’s internal layout can vary, so locate wkhtmltopdf.exe after extraction.

Run it by full path

\"C:\Program Files\wkhtmltopdf\bin\wkhtmltopdf.exe\" https://example.com example.pdf

PowerShell requires the call operator (&) when invoking a quoted executable path:

& \"C:\Program Files\wkhtmltopdf\bin\wkhtmltopdf.exe\" https://example.com example.pdf

Add the executable directory to PATH

Find the directory that contains wkhtmltopdf.exe. In Windows, open System Properties → Advanced → Environment Variables. Add that directory to either your user Path (only your account) or system Path (all users). Open a new terminal afterwards.

You can also append a user PATH entry from PowerShell. Replace the directory with the location you found:

$wkhtmlDir = 'C:\Program Files\wkhtmltopdf\bin'
$currentPath = [Environment]::GetEnvironmentVariable('Path', 'User')
if ($currentPath -notlike "*$wkhtmlDir*") {
  [Environment]::SetEnvironmentVariable('Path', "$currentPath;$wkhtmlDir", 'User')
}

Start a new terminal after changing PATH. Existing processes keep their original environment.

4. Verify the installation

Check the version

wkhtmltopdf --version

A successful command prints the program name and version information. Save this output with your deployment notes so upgrades can be identified.

Convert a public URL

wkhtmltopdf https://example.com example.pdf

Confirm that example.pdf appears in the current directory and opens normally.

Convert a local HTML file

Create hello.html:

<!doctype html>
<html>
<head><meta charset=\"utf-8\"><title>Test</title></head>
<body><h1>wkhtmltopdf works</h1></body>
</html>

Then run:

wkhtmltopdf .\hello.html .\hello.pdf

A local conversion helps distinguish installation and PATH problems from DNS, TLS, firewall, or remote-page rendering problems.

5. Useful command options

Need	Example
Set page orientation	`wkhtmltopdf --orientation Landscape input.html output.pdf`
Set paper size	`wkhtmltopdf --page-size A4 input.html output.pdf`
Set margins	`wkhtmltopdf --margin-top 15mm --margin-bottom 15mm input.html output.pdf`
Print background graphics	`wkhtmltopdf --background input.html output.pdf`
Wait for JavaScript	`wkhtmltopdf --javascript-delay 2000 https://example.com output.pdf`
Use a custom user agent	`wkhtmltopdf --custom-header User-Agent \"Mozilla/5.0\" https://example.com output.pdf`
Load a local asset	`wkhtmltopdf --enable-local-file-access input.html output.pdf`

Option support depends on the 0.12.6 build. Run wkhtmltopdf --extended-help to inspect the options available in your binary.

6. Troubleshooting Windows errors

“wkhtmltopdf is not recognized”

Close the terminal and open a new one after installation or PATH changes.
Run where.exe wkhtmltopdf to see whether Windows can locate it.
Use the executable’s full path to confirm that the binary itself works.
Check that PATH contains the directory containing wkhtmltopdf.exe, not only its parent directory.

PowerShell says the path is not a command

Quote paths containing spaces and prefix them with &:

& \"C:\Program Files\wkhtmltopdf\bin\wkhtmltopdf.exe\" input.html output.pdf

The URL conversion fails but local HTML works

Check DNS, proxy and firewall rules, certificate validation, redirects, and whether the site requires authentication or blocks automated clients. Retry with a known public URL. A local conversion proves the installation while avoiding network variables.

The PDF is blank or missing images

Some pages render content asynchronously. Try --javascript-delay, confirm that image URLs are reachable from the machine, and check whether local files require --enable-local-file-access. Legacy Qt WebKit may not support modern browser APIs used by the page.

Fonts or characters are wrong

Ensure the required fonts are installed on Windows, declare UTF-8 with a meta tag, and use --encoding utf-8 when needed. Missing web fonts can also result from blocked network requests.

“Cannot connect to X server” or display errors

Official wkhtmltopdf binaries are designed to run headlessly. Verify that you downloaded the official Windows binary and are not wrapping it in an unnecessary display-server configuration.

Installer will not run

Confirm that the download completed, Windows architecture is compatible, and security software has not quarantined the executable. If policy prevents installers, use the matching 7z archive and configure PATH manually.

7. Security considerations

The official downloads page warns: “Do not use wkhtmltopdf with any untrusted HTML – be sure to sanitize any user-supplied HTML/JS, otherwise it can lead to complete takeover of the server it is running on!” Treat HTML, JavaScript, CSS, URLs, and local file references as untrusted input in automated systems.

Sanitize user-supplied HTML and JavaScript before conversion.
Run conversions in a restricted account or isolated worker.
Limit outbound network access where possible.
Do not expose arbitrary file paths or unrestricted local-file access.
Set execution timeouts and clean up generated files.

8. Performance, reliability and maintenance

Pin the version: use 0.12.6 consistently and record the download source and architecture.
Warm workers: keep a controlled worker process available if you convert many documents, rather than repeatedly starting processes.
Bound work: set job timeouts and limit page size, JavaScript delay and concurrent conversions.
Separate failures: log the command, exit code, stderr, input URL or file, and output path.
Test representative pages: include JavaScript-heavy pages, images, non-Latin text and local assets in regression checks.
Plan for legacy rendering: Qt WebKit is older than current Chromium, so modern CSS and browser APIs may require page-specific fallbacks.

9. Or skip the browser setup

If your goal is a clean website image or PDF rather than maintaining a Windows renderer, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF. Its capture flow accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be turned off.

cURL

curl -G \"https://api.screenshotneo.com/v1/shot\" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

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)

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}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const buffer = Buffer.from(await res.arrayBuffer());
require('fs').writeFileSync('shot.webp', buffer);

See the ScreenshotNeo API documentation for options such as full-page capture, CSS selectors, device presets, retina scale, PDF paper and margins, custom CSS or JavaScript, waits, blocked resources, headers, cookies, geolocation, caching, signed links, asynchronous jobs, bulk capture and usage reporting. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed as clean shots, and the response identifies the result with X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account and start with 1,000 screenshots per month at no charge.

10. FAQ

Which wkhtmltopdf version should I install?

Use the stable 0.12.6 Windows build from the official downloads page and document the architecture and date in your deployment records.

Do I need to install a browser?

No. wkhtmltopdf includes a headless rendering engine and does not require a separate display service.

Why does PATH work in one terminal but not another?

Each process receives its environment when it starts. Open a new terminal after changing PATH.

Should I use the installer or 7z archive?

Use the installer for guided setup and automatic PATH configuration. Use the archive for portable, policy-controlled or manually pinned deployments.

Can wkhtmltopdf safely process user-submitted HTML?

Not without sanitization and isolation. The project explicitly warns that unsanitized HTML or JavaScript can lead to complete server takeover.