Use wkhtmltoimage with an input URL or HTML file followed by an output filename:
wkhtmltoimage [OPTIONS]... <input file> <output file>
For example, wkhtmltoimage https://example.com capture.png renders the page to a PNG. The same command can create JPEG or other supported image formats by changing the filename extension or setting --format. This guide explains installation checks, URL and local-file captures, viewport and crop controls, JavaScript timing, authentication, troubleshooting, and when a current screenshot API is a better fit.
What wkhtmltoimage does
The wkhtmltopdf project describes wkhtmltoimage as an open-source (LGPLv3) command-line tool that renders HTML into image formats with the Qt WebKit rendering engine. It runs headlessly, so a display service is not required. The program accepts a remote URL or a local HTML document, applies command-line rendering options, and writes one image file.
The upstream GitHub repository is archived (shown as archived on January 2, 2023). Rendering behavior therefore depends heavily on the binary supplied by your operating system or distribution. Ubuntu Noble, for example, lists package version 0.12.6-2build2; that identifier is specific to that distribution and is not a universal current version. Always inspect the binary installed on your machine.
#1 Best Overall
Check installation and version
Install wkhtmltoimage using the package manager for your operating system or a precompiled binary from the official project workflow. Package names differ: some distributions provide it with the wkhtmltopdf package, while others split the executable. After installation, run:
wkhtmltoimage --version wkhtmltoimage --help | head -n 40
If the shell reports “command not found,” install the package, reopen the terminal, or invoke the executable by its full path. Use --help to confirm which options your build includes; downstream builds can differ in defaults and available features.
Take a basic screenshot from a URL
- Open a terminal on the machine where wkhtmltoimage is installed.
- Run the URL and output filename as positional arguments:
wkhtmltoimage https://example.com capture.png
- Open
capture.pngwith an image viewer and check the terminal output for warnings.
The URL must be reachable from that machine. Quote URLs containing shell characters:
wkhtmltoimage "https://example.com/search?q=html%20rendering" search.png
Use an explicit format when the extension is ambiguous:
Recommended Free Tools
wkhtmltoimage --format png https://example.com capture.bin wkhtmltoimage --format jpg --quality 85 https://example.com capture.jpg
--quality applies to JPEG and accepts an integer from 0 to 100. The documentation does not establish a universally best quality value, so choose one based on your file-size and visual-quality requirements.
Render a local HTML document
Pass the HTML path in the input position:
wkhtmltoimage report.html report.png
For a file URL, use an absolute path and the file:// scheme appropriate to your platform:
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
wkhtmltoimage "file:///home/alex/report.html" report.png
Local pages commonly reference CSS, JavaScript, fonts, and images beside the HTML file. Local-file security settings control whether those dependencies can be read. If your build blocks them, enable access narrowly:
wkhtmltoimage --enable-local-file-access --allow /home/alex/report-assets report.html report.png
Repeat --allow for each required directory. Avoid granting a broad filesystem path when a small asset directory is sufficient. Conversely, --disable-local-file-access prevents local-file access when you need a stricter boundary.
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 errorsControl the viewport and output dimensions
Screen width and height
--width <int> supplies a screen-width hint, while --height <int> sets screen height. Height otherwise defaults from page content. If you require a strict width, disable smart width as documented by the manpage:
wkhtmltoimage --width 1440 --disable-smart-width https://example.com desktop.png
Smart-width behavior and responsive breakpoints can vary by build. Treat the result as a rendering setting to verify, not as a guarantee that a site will match a current desktop browser.
Crop and scale
Use --crop-w and --crop-h for crop dimensions, and --crop-x and --crop-y for the crop origin. --zoom <float> changes the rendered scale:
wkhtmltoimage --width 1280 --crop-x 0 --crop-y 0 --crop-w 900 --crop-h 600 --zoom 1.25 https://example.com area.png
Crop coordinates are measured in the rendered page coordinate system. If the crop is empty or shifted, first capture without cropping, then adjust coordinates against that full image.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, 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 minuteRank #3
Wait for JavaScript and dynamic content
JavaScript is enabled by default in typical builds, but the page may still be captured before asynchronous content appears. You can disable scripts with --disable-javascript or add a fixed wait:
wkhtmltoimage --javascript-delay 3000 https://example.com/dashboard delayed.png
The delay is in milliseconds. It is a timer, not a confirmation that data or animations have finished. A status-based alternative is:
wkhtmltoimage --window-status ready https://example.com/app app.png
The page must set the corresponding window status (for example, through the page’s JavaScript) for this approach to work. Neither setting guarantees compatibility with every modern JavaScript framework or browser API because wkhtmltoimage uses the older Qt WebKit engine.
Make a page deterministic before capture
- Use a fixed viewport and a known URL.
- Prefer a page state that does not depend on an animation still in progress.
- Set a window-status value only when you control the page and can signal readiness reliably.
- Capture several representative pages when choosing a delay; no universal delay is established by the documentation.
Authentication, headers, cookies, and network controls
The manpage documents options for cookies, custom headers, authentication, proxies, and client certificates. Exact option names and syntax can vary by build, so confirm them with wkhtmltoimage --help. A typical pattern for a protected endpoint is:
wkhtmltoimage --username alice --password 'replace-with-password' --custom-header Authorization 'Bearer replace-with-token' https://example.com/private private.png
Do not put secrets in shell history or shared process listings when your environment treats them as sensitive. Prefer a short-lived token, a protected execution environment, or a cookie file supported by your installed build. For a corporate proxy, configure the documented proxy options and verify that DNS, TLS, and outbound access work from the same host running the command.
Handle errors and inspect diagnostics
JavaScript errors or missing content
Add JavaScript diagnostics and a more verbose log level:
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
wkhtmltoimage --debug-javascript --log-level info --javascript-delay 3000 https://example.com page.png
Browser-console output is limited compared with a modern developer-tools console. Use the page’s own logs or a simpler test document to isolate the failing script.
Resource or page-load failures
The manpage provides --load-error-handling and --load-media-error-handling. Select the behavior your automation requires, then check the process exit status:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
wkhtmltoimage --load-error-handling ignore https://example.com page.png echo $?
Ignoring an error can produce an incomplete image, so record the command output and inspect the result rather than treating a zero-error workflow as proof that every resource loaded.
Blank image or missing local assets
- Confirm the input URL or local path independently with a browser or an HTTP client.
- For local HTML, add
--enable-local-file-accessand narrowly scoped--allowpaths. - Check that relative URLs resolve from the HTML document’s directory.
- Try an absolute asset URL or embed a small test image to identify a path problem.
- Verify that the output directory is writable and that an existing file is not being mistaken for the new capture.
Wrong size or unexpected layout
Record the exact width, height, zoom, smart-width setting, and installed version. Responsive CSS may choose a different layout at the selected width. Capture a full image first, then apply crop coordinates. If text is clipped, increase the page height or remove cropping before changing zoom.
Automation patterns
Shell loop for several URLs
while IFS= read -r url; do
name=$(printf '%s' "$url" | sed 's#[^A-Za-z0-9._-]#_#g')
wkhtmltoimage --width 1440 --javascript-delay 1500 "$url" "captures/${name}.png"
done < urls.txt
Create the captures directory first and keep URL-to-filename mapping if reproducibility matters. Limit concurrency according to the CPU and memory available to your host; the tool documentation does not provide a universal throughput figure.
Use an explicit exit check
if wkhtmltoimage https://example.com capture.png; then printf '%sn' 'Screenshot created' else printf '%sn' 'Screenshot command failed' >&2 exit 1 fi
Keep stderr logs with the output so a later review can distinguish a valid page from a partially rendered one.
Known compatibility limits
wkhtmltoimage’s Qt WebKit engine is not equivalent to a current Chromium, Firefox, or Safari engine. Modern CSS, JavaScript APIs, web components, client-side navigation, bot checks, and authentication flows may render differently or fail. The available options help with timing and resources, but they do not promise pixel-identical modern-browser output. For a legacy or controlled HTML page, it can still be a practical command-line renderer; for a public site, validate representative pages before depending on it in production.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF, so you do not install or maintain a headless browser. 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 or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed; each response identifies the page verdict and billing result in X-Page-Verdict and X-Billed headers.
Using the API requires an access key. The complete parameter reference is in the ScreenshotNeo documentation.
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 data = Buffer.from(await res.arrayBuffer());
require('node:fs').writeFileSync('shot.webp', data);
ScreenshotNeo also supports full-page captures with lazy images loaded, CSS-selector element captures, dark mode, 12 device presets and arbitrary viewports, retina scale, custom CSS and JavaScript, clicks, selector or network-idle waits, request and resource blocking, headers, cookies, user agents, Authorization, timezone, geolocation, transparent backgrounds, resizing, chosen-TTL caching, signed public image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Its parameter names are compatible with those used by other screenshot APIs, which can simplify migration. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →| Plan | Included screenshots | Price |
|---|---|---|
| Free | 1,000 per month | $0, no card |
| Starter | 3,000 | $5 |
| Growth | 15,000 | $15 |
| Pro | 60,000 | $39 |
| Scale | 250,000 | $99 |
| Business | 1,000,000 | $249 |
Yearly billing provides two months free, and every feature is included on every plan. Create a free ScreenshotNeo account to get 1,000 screenshots each month with no card.
Frequently asked questions
Can wkhtmltoimage create a PDF?
No. wkhtmltoimage writes images; the related wkhtmltopdf command creates PDFs. ScreenshotNeo’s API can return a PDF when that is the required output.
Is wkhtmltoimage available on every Linux distribution?
Availability and package versions depend on the distribution. Check your package manager and then verify the installed executable with wkhtmltoimage --version.
Why does a page look different from Chrome?
The engines differ: wkhtmltoimage uses Qt WebKit, and its CSS and JavaScript support does not guarantee current-browser fidelity.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Should I use a fixed delay or window status?
Use a fixed delay when you cannot modify the page; use --window-status when you control the page and can emit a reliable readiness value. Validate either choice on the pages you capture.
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.
