On Windows, using wkhtmltopdf means installing a Windows build, making sure the folder containing wkhtmltopdf.exe is on PATH, verifying the executable, and running the pattern wkhtmltopdf input output.pdf. For example, convert a web page with wkhtmltopdf https://example.com example.pdf or a local document with wkhtmltopdf C:workinvoice.html C:workinvoice.pdf.
This guide covers installation, PATH configuration, PDF options, local assets, JavaScript timing, authentication, diagnostics, security, and alternatives for pages that the tool cannot render reliably.
What wkhtmltopdf does
wkhtmltopdf is an open-source LGPLv3 command-line program that renders HTML into PDF using the Qt WebKit engine. It runs headlessly, so Windows does not need a separate display server. Its companion program, wkhtmltoimage, renders HTML to an image.
The command treats each input as a page object and the final argument as the output document. Builds that include the relevant features can also combine multiple page objects, covers, and tables of contents.
#1 Best Overall
- 14" diagonal, 1366x768 resolution, HD BrightView LED, Glossy NON-TOUCH Display
Install wkhtmltopdf on Windows
Use a reputable Windows installer
- Download a Windows installer from a reputable wkhtmltopdf distribution.
- Run the installer and accept the license.
- Leave wkhtmltopdf selected when the component list appears.
- Enable the option to modify the system
PATH, if the installer offers it. - Choose the destination folder and finish the installation.
Installer choices vary between distributions. If there is no PATH option, you can add the executable directory yourself in the next section.
Verify the installation
Open a new Command Prompt or PowerShell window and run:
wkhtmltopdf --versionA working installation prints version and build information. Check which executable Windows will use with:
where wkhtmltopdfOpening a new terminal matters because an already-open window may still have the old PATH value.
Fix “wkhtmltopdf is not recognized”
If Windows cannot find the command, call the executable by its full path first:
"C:Program Fileswkhtmltopdfbinwkhtmltopdf.exe" --versionIf that works, add the directory containing wkhtmltopdf.exe to PATH:
- Open Windows Search and type environment variables.
- Select Edit the system environment variables.
- Click Environment Variables.
- Under User variables (for only your account) or System variables (for all users), select
Pathand click Edit. - Click New and add the executable directory, commonly
C:Program Fileswkhtmltopdfbin. - Confirm every dialog, open a new terminal, and run
where wkhtmltopdffollowed bywkhtmltopdf --version.
Use the path shown by your installation rather than assuming the example directory. If where returns multiple copies, remove stale entries or place the intended directory first.
Convert a URL or local HTML file
Convert a remote page
wkhtmltopdf https://example.com example.pdfThe first argument is the URL and the second is the output file. Quote paths containing spaces:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
- 256 GB SSD of storage.
- Multitasking is easy with 16GB of RAM
- Equipped with a blazing fast Core i5 2.00 GHz processor.
wkhtmltopdf "https://example.com/invoices/42" "C:UsersPublicDocumentsinvoice.pdf"Convert a local file
wkhtmltopdf C:workinvoice.html C:workinvoice.pdfFor a file whose path contains spaces:
wkhtmltopdf "C:work filesinvoice.html" "C:work filesinvoice.pdf"Local CSS, images, fonts, and scripts may be blocked by the build’s local-file policy. Permit only the directory that contains the required assets:
wkhtmltopdf --allow C:workassets C:workinvoice.html C:workinvoice.pdfSome builds require the broader switch below for local resources:
wkhtmltopdf --enable-local-file-access C:workinvoice.html C:workinvoice.pdfPrefer --allow when it is sufficient because it is narrower. Do not grant access to an entire drive merely to make one image load.
Control page layout and output
Put global options before the input and output arguments. Common layout options include:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →| Need | Option | Example |
|---|---|---|
| Paper size | --page-size |
--page-size A4 |
| Orientation | --orientation |
--orientation Landscape |
| Top margin | --margin-top |
--margin-top 15mm |
| Right margin | --margin-right |
--margin-right 12mm |
| Bottom margin | --margin-bottom |
--margin-bottom 15mm |
| Left margin | --margin-left |
--margin-left 12mm |
A complete example is:
wkhtmltopdf --page-size A4 --orientation Landscape --margin-top 12mm --margin-right 12mm --margin-bottom 12mm --margin-left 12mm https://example.com report.pdfUse wkhtmltopdf -H to display the help generated by the exact binary installed on your machine. That is the authoritative list for your build, because packaged builds can differ in enabled features.
Handle JavaScript and delayed rendering
JavaScript is enabled by default in typical builds, but wkhtmltopdf uses an old WebKit engine. A page that renders after an API call, animation, or client-side route change may be captured before its content is ready.
Wait a fixed amount of time
wkhtmltopdf --javascript-delay 1000 https://example.com/dynamic report.pdfThe value is milliseconds. Increase it only as much as needed; a long delay increases every conversion’s runtime.
Wait for a page status
If the page can set a window status after its data is ready, wait for that value:
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Rank #3
- FULL HD IPS DISPLAY - Enjoy vibrant, crystal-clear images with 178-degree wide-viewing angles
- AMD RYZEN 3 30 PROCESSOR - Everyday performance you can count on; Multitask, stream, game casually, and edit photos smoothly with responsive power and vibrant HDR visuals
- ENJOY UP TO 14 HOURS AND 15 MINUTES OF BATTERY LIFE - HP Fast Charge restores battery from 0 to 50% in approximately 45 minutes
- AMD RADEON 610M GRAPHICS - Experience smooth entertainment; Built for streaming and multitasking, enjoy realistic visuals and efficient performance for work and play
- STORAGE AND MEMORY - 512 GB PCIe NVMe M.2 SSD offers fast speed and efficient storage; and 8 GB LPDDR5 RAM memory boosts performance with higher bandwidth
wkhtmltopdf --window-status READY https://example.com/dynamic report.pdfThis requires the page’s JavaScript to set the expected status. If it never does, the conversion can wait indefinitely or fail according to the build’s behavior.
Disable scripts deliberately
For static, trusted HTML where scripts are unnecessary:
wkhtmltopdf --disable-javascript C:workstatic.html C:workstatic.pdfDisabling JavaScript can improve predictability, but it removes script-generated content.
Authentication, headers, cookies, and proxies
For protected pages, wkhtmltopdf provides options for common request requirements:
--username USER --password PASSWORDsupplies basic credentials where supported.--cookie NAME VALUEsends a cookie to the page.--custom-header Header Valueadds a request header.--proxy proxy-host:portroutes requests through a proxy.
Example:
wkhtmltopdf --cookie session_id abc123 --custom-header Authorization "Bearer TOKEN" https://example.com/account account.pdfDo not place long-lived secrets in scripts, command histories, shared build logs, or PDF metadata. Use the smallest credential scope possible and test whether the target server permits the requested authentication method.
Diagnose failures before changing many options
- Run
wkhtmltopdf --versionandwhere wkhtmltopdf. - Convert a minimal public URL.
- Convert a minimal local HTML file.
- Check that CSS, images, fonts, and scripts are reachable from the conversion process.
- Add only the option that addresses the observed failure.
This sequence separates an installation or PATH problem from a page-specific problem. Use --log-level info for more useful conversion messages and --debug-javascript when script errors are suspected.
Common errors and fixes
| Symptom | Likely cause | What to try |
|---|---|---|
| Command not recognized | Executable directory is missing from PATH, or the terminal is stale. | Run the full path, add its directory to PATH, open a new terminal, then use where wkhtmltopdf. |
| Blank or incomplete PDF | JavaScript has not finished or the page requires a newer browser engine. | Try --javascript-delay or --window-status; if the site depends on modern JavaScript, use a maintained browser-based tool. |
| Images, CSS, or fonts are missing from local HTML | Local-file access is restricted, or asset paths are wrong. | Use an explicit --allow directory, or the build’s --enable-local-file-access switch; verify paths. |
| Network resource errors | DNS, proxy, authentication, TLS, or an unavailable asset. | Test the URL separately, configure --proxy, credentials, cookies, or headers, and inspect logs. |
| Some resources fail but a PDF is produced | Optional assets failed during loading. | Fix the underlying resource first. Use --load-error-handling ignore only when you understand which failures are acceptable. |
| Layout differs from the browser | Qt WebKit does not match current browser engines and CSS support. | Simplify the HTML/CSS or choose a current rendering engine for modern pages. |
When requesting project help, provide the wkhtmltopdf version, Windows version, and a reproducible HTML/CSS/JavaScript example, rather than only a screenshot of the failure.
Security and maintenance limitations
wkhtmltopdf’s underlying components are old: Qt 4 has been unsupported since 2015, and the WebKit used by wkhtmltopdf has not been updated since 2012. The project 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!”
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsRank #4
- 14” Diagonal HD BrightView WLED-Backlit (1366 x 768), Intel Graphics,
- Intel Celeron Dual-Core Processor Up to 2.60GHz, 4GB RAM, 64GB SSD
- 3x USB Type A,1x SD Card Reader, 1x Headphone/Microphone
- 802.11a/b/g/n/ac (2x2) Wi-Fi and Bluetooth, HP Webcam with Integrated Digital Microphone
- Windows 11 OS, Dale Blue
Therefore, treat both installers and input documents as security decisions:
- Download installers from a reputable distribution and verify what you are installing.
- Never feed arbitrary user HTML or JavaScript directly into a privileged conversion process.
- Sanitize content and isolate conversion from sensitive files and credentials.
- Use restrictive Windows accounts, directories, and process permissions.
- Do not copy Linux-specific AppArmor commands to Windows; apply equivalent Windows security controls.
When another renderer is the better choice
The project distinguishes controlled report generation from dynamic websites. For controlled reports, it suggests WeasyPrint or the commercial Prince tool. For pages that depend on dynamic JavaScript, it suggests Puppeteer or similar wrappers. Check current Windows support, output requirements, and licensing before migrating.
| Requirement | wkhtmltopdf fit | Consider instead |
|---|---|---|
| Existing simple HTML templates and familiar command lines | Good fit when assets and layout are controlled. | Keep wkhtmltopdf if its output is stable. |
| Modern CSS or client-rendered JavaScript | Risk of missing or outdated rendering behavior. | Puppeteer or another current browser wrapper. |
| Controlled report generation with a maintained stack | Maintenance limitations require extra review. | WeasyPrint or Prince, subject to requirements and licensing. |
| Remote screenshots or PDFs without managing a Windows browser setup | Requires local installation and page-specific tuning. | ScreenshotNeo API or MCP server. |
Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server. It accepts a URL in one request and can return PNG, JPEG, WebP, or PDF. Before capture, it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks or 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.
For a URL-to-file call, see the ScreenshotNeo documentation and run:
Recommended Free Tools
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}`);ScreenshotNeo also supports full-page captures with lazy images loaded, CSS-selector element captures, dark mode, 12 device presets and custom viewports, retina scale, PDF paper size and margins, page ranges, custom CSS and JavaScript, click-before-capture actions, selector hiding, selector or delay or network-idle waits, request and resource blocking, custom headers, cookies, user agents and Authorization, timezone and geolocation, transparent backgrounds, image resizing, selectable-TTL caching, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which can simplify a migration.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Create a free ScreenshotNeo account to start without a card.
Practical decision checklist
- Choose wkhtmltopdf for controlled HTML that already renders correctly in its WebKit engine.
- Use explicit local-file allowances rather than broad filesystem access.
- Add JavaScript waiting only when the page needs it, and keep delays bounded.
- Sanitize and isolate every untrusted input.
- Move to a current browser renderer when modern CSS or JavaScript is essential.
- Use an API when you want remote capture, automated cleanup, or an MCP workflow instead of maintaining a Windows installation.
Frequently Asked Questions
Can wkhtmltopdf create more than one PDF page?
Yes. HTML that exceeds the selected paper dimensions flows across pages; builds with page-object support can also combine multiple page objects, covers, and tables of contents.
Should I use the system PATH or a full executable path in automation?
A full path is explicit and avoids selecting the wrong copy when several versions are installed. PATH is convenient for interactive use and scripts that run in a controlled environment.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Why does increasing the JavaScript delay sometimes not help?
A delay only gives the old WebKit engine more time. It cannot add support for browser features the engine does not implement, and it cannot fix authentication, blocked resources, or a page that never reaches its ready state.
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.
