Download the Windows package from the official wkhtmltopdf downloads page, choose the 32-bit or 64-bit build that matches your system, install or extract it, then run wkhtmltoimage from its folder or add that folder to PATH. The executable is bundled with the wkhtmltopdf command-line package, even when the installer name says wkhtmltox or wkhtmltopdf.
The current stable series listed by the project is 0.12.6, released June 11, 2020. That age matters: follow the published package instructions, but check the release page for packaging changes and do not assume compatibility or active maintenance on every current Windows edition.
What you need before installing
- A supported Windows account that can install software, or permission to extract an archive to a folder you control.
- The official download page: https://wkhtmltopdf.org/downloads.html. It directs downloads to the project’s GitHub releases.
- A decision between the conventional installer and a portable 7z archive.
wkhtmltoimage is one of two headless Qt WebKit command-line tools in the package; wkhtmltopdf creates PDFs and wkhtmltoimage creates raster images from web pages or HTML files.
Choose the correct Windows package
| Choice | Published label | Best for | What you do |
|---|---|---|---|
| 64-bit installer | Vista or later | Most modern 64-bit Windows systems | Run the installer wizard |
| 32-bit installer | Vista or later | 32-bit Windows or a required 32-bit environment | Run the installer wizard |
| 64-bit 7z archive | XP/2003 or later | Portable or manual deployments | Extract files yourself |
| 32-bit 7z archive | XP/2003 or later | Older 32-bit environments | Extract files yourself |
The project does not publish a performance comparison between installer and archive forms. Match the architecture first. On Windows 10 or 11, confirm the system type under Settings → System → About → System type; a 64-bit operating system is normally the appropriate choice unless a 32-bit dependency dictates otherwise.
#1 Best Overall
Install with the Windows installer
- Open the official downloads page and follow its link to the GitHub release for 0.12.6 or any later package the project lists.
- Download the Windows installer whose 32-bit or 64-bit architecture matches your system. The installer label refers to Vista or later.
- When the download finishes, open the installer. If Windows SmartScreen displays a warning, verify that the file came from the official release link before deciding whether to continue.
- Accept the licence, choose the destination folder, and complete the wizard. Record the destination; you will need it if PATH is not updated automatically.
- Open a new Command Prompt or PowerShell window. A new shell is important because existing shells do not always see environment-variable changes.
- Run
wkhtmltoimage --version. A successful installation should print the installed version rather than a “not recognized” error.
The installer may create a directory such as C:Program Fileswkhtmltopdfbin, but do not assume that exact path. Use the folder shown by the wizard or locate wkhtmltoimage.exe in File Explorer.
Use the portable 7z archive
- Download the matching 32-bit or 64-bit 7z package from the official release link. The project labels these archives XP/2003 or later.
- Install a tool that can extract 7z files if Windows does not already provide one.
- Extract the archive to a stable directory, for example
C:Toolswkhtmltopdf. Avoid extracting into a temporary Downloads subfolder that may later be deleted. - Open a shell in the directory containing
wkhtmltoimage.exeand verify it directly:.wkhtmltoimage.exe --versionin PowerShell, orwkhtmltoimage.exe --versionin Command Prompt.
An archive does not create Start-menu entries or necessarily modify PATH. That is useful for portable deployments, but you must maintain the folder and configure invocation yourself.
Make wkhtmltoimage available everywhere
Wrappers and shell sessions expect the executable directory to be on PATH, or they require the full executable path. If a command works only when you are in its installation folder, add that folder to your user PATH.
- Copy the directory that contains
wkhtmltoimage.exe, not the path to the executable itself. - Open Windows Search → Edit environment variables for your account.
- Click Environment Variables. Under User variables, select Path, choose Edit, then New.
- Paste the bin directory, select OK through each dialog, and close existing shells.
- Open a fresh Command Prompt and run
where wkhtmltoimage, followed bywkhtmltoimage --version.
For a one-off call, avoid changing PATH and use a quoted full path instead:
"C:Program Fileswkhtmltopdfbinwkhtmltoimage.exe" https://example.com output.jpgCapture a web page or local HTML file
Web URL
wkhtmltoimage https://example.com output.jpgThe final argument determines the output file type by extension in common usage. Use .png, .jpg, or another format supported by your build. For a full-page capture, add the project’s relevant command-line options and inspect the resulting dimensions; rendering behavior can vary with page scripts and the old Qt WebKit engine.
Local HTML
wkhtmltoimage "C:workpage.html" "C:workpage.png"Use an absolute file:/// URL when a relative path is ambiguous:
wkhtmltoimage "file:///C:/work/page.html" "C:workpage.png"Local pages that reference stylesheets, fonts, images, or scripts must be able to resolve those resources. Keep related files in their expected relative locations, and test with a simple page before diagnosing a complex application.
Automation examples
Command Prompt or PowerShell
wkhtmltoimage --version
wkhtmltoimage https://example.com C:workexample.pngPython
import subprocess
subprocess.run([
r"C:Program Fileswkhtmltopdfbinwkhtmltoimage.exe",
"https://example.com",
r"C:workexample.png",
], check=True)Using the absolute path makes the script independent of PATH. If you deliberately configured PATH, replace the first list item with "wkhtmltoimage".
Rank #3
Node.js
import { execFile } from "node:child_process";
execFile(
"wkhtmltoimage",
["https://example.com", "C:\work\example.png"],
(error, stdout, stderr) => {
if (error) throw error;
console.log(stderr || stdout);
}
);cURL alternative through ScreenshotNeo
If your goal is an automated website screenshot rather than maintaining a local browser binary, ScreenshotNeo provides a one-request API. See the ScreenshotNeo documentation for the complete parameter reference.
Or skip the browser setup
ScreenshotNeo accepts a URL and returns PNG, JPEG, WebP, or PDF. It removes cookie-consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)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 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 try it.
Troubleshooting
“wkhtmltoimage is not recognized”
The shell cannot find the executable. Run it from the installation directory, use its quoted full path, or add the containing directory to user PATH. Open a new shell and confirm with where wkhtmltoimage.
Recommended Free Tools
The wrong architecture was downloaded
Recheck Settings → System → About → System type and install the matching 32-bit or 64-bit package. Do not infer architecture from the installer filename alone.
The installer cannot run
Confirm that you downloaded a Windows installer rather than a 7z archive, and verify that the package came from the official downloads page. If organizational policy blocks installers, use the archive and configure PATH manually.
The output is blank or incomplete
The 0.12.6 engine is old and pages may depend on JavaScript, modern CSS, delayed network calls, authentication, or anti-bot controls that its Qt WebKit renderer cannot reproduce. Test a simple public page, check resource paths for local HTML, and inspect command output for errors. A successful process exit does not prove that every dynamic element rendered.
Images, fonts, or styles are missing
Check relative URLs, file permissions, and whether local assets are reachable from the HTML file. Try absolute local paths or a small self-contained test document to isolate the resource problem.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Automation hangs or consumes excessive resources
Set an external process timeout in Python, Node.js, or your job runner. Terminate stuck processes and retain stderr for diagnosis. Limit concurrency until you understand the memory behavior of your pages.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Security and maintenance limits
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!” Treat that warning as applying to automated wkhtmltoimage workflows as well: untrusted HTML and JavaScript can access resources or trigger behavior you did not intend. Sanitize input, isolate rendering jobs, restrict network access where possible, and never pass arbitrary user HTML directly to a privileged server process.
Version 0.12.6 was released in 2020, and the repository is archived. The official compatibility labels (Vista or later for installers; XP/2003 or later for archives) are published package labels, not a guarantee that every current Windows build or website will render reliably. Pin the package you deploy, document its path, and recheck the official release page before introducing it into a new production system.
Frequently asked questions
Frequently Asked Questions
Does installing wkhtmltopdf also install wkhtmltoimage?
Yes. The Windows command-line package contains both executables; the installer name may mention wkhtmltopdf or wkhtmltox.
Can I run the 7z version without administrator rights?
Often, if you extract it to a directory where your account can write and invoke the executable directly. Whether policy permits execution is controlled by your Windows environment.
Which output formats can wkhtmltoimage create?
The command is commonly used for PNG and JPEG output, with the format selected by the output filename or applicable command options. Confirm behavior with your installed build.
Is wkhtmltoimage a modern browser engine?
No. It is based on the project’s Qt WebKit tooling, and stable 0.12.6 dates from June 2020. Modern JavaScript and CSS may not render as expected.
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.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitches
