Use wkhtmltoimage, not wkhtmltopdf, when the result must be a PNG, JPEG, or WebP image. The basic command is wkhtmltoimage https://example.com screenshot.png. wkhtmltopdf is the companion program for PDF output. Both are documented as headless Qt WebKit command-line tools, so they do not require a display service.
This guide shows how to install and verify the executable, capture remote and local pages, control dimensions and cropping, wait for JavaScript, pass cookies or headers, diagnose incomplete renders, and decide when a modern browser-based service is a better fit.
Use the correct executable
The name wkhtmltopdf often causes confusion because the project ships two related utilities:
| Need | Executable | Typical command |
|---|---|---|
| Image file | wkhtmltoimage |
wkhtmltoimage https://example.com screenshot.png |
| PDF document | wkhtmltopdf |
wkhtmltopdf https://example.com page.pdf |
The wkhtmltopdf manual documents version 0.12.6 with patched Qt. The project describes both programs as open-source software under LGPLv3 and as utilities that run entirely headless. Its repository is archived and read-only, however, so package maintainers may ship different binaries and option sets. Treat the executable installed on your machine as the authority.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
Check your installation before capturing
- Find the image executable. Run
wkhtmltoimage --version. If your shell reports that the command is not found, install a package that includeswkhtmltoimageor use the full path to the binary supplied by your platform. - Inspect supported options. Run
wkhtmltoimage --helpand compare the output with the options below. Distribution builds can differ. - Confirm write permissions. Choose an output directory where the current user can create files.
- Test a simple page. Start with a small, publicly reachable URL before adding cookies, JavaScript waits, or local-file permissions.
wkhtmltoimage --version
wkhtmltoimage --help
wkhtmltoimage https://example.com screenshot.pngOpen the resulting image and check its pixel dimensions, page state, fonts, and external assets. A successful process exit only tells you that the executable produced a file; it does not prove that every script or image on the page finished loading.
Capture a remote page
The documented syntax is:
wkhtmltoimage [OPTIONS]... <input file> <output file>The input can be an HTTP(S) URL or a local HTML path. For a remote page:
wkhtmltoimage https://example.com screenshot.pngThe output extension normally communicates the desired format. You can make the format explicit when a downstream system requires it:
wkhtmltoimage --format png https://example.com screenshot.png
wkhtmltoimage --format jpg https://example.com screenshot.jpg
wkhtmltoimage --format webp https://example.com screenshot.webpUse an absolute output path in scheduled jobs so that the file is not written unexpectedly relative to the job’s working directory.
Capture a local HTML file and its assets
Pass the file path as the input:
wkhtmltoimage /var/www/site/index.html local-page.pngLocal pages commonly reference CSS, images, fonts, or JavaScript in sibling directories. Local-file access is controlled by command-line options, and builds can handle it differently. If your page needs a specific asset directory, allow that directory explicitly:
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
wkhtmltoimage --allow /var/www/site /var/www/site/index.html local-page.pngTo reduce exposure to local resources, disable local-file access and only allow the directories you require:
wkhtmltoimage --disable-local-file-access --allow /var/www/site /var/www/site/index.html local-page.pngTest relative URLs carefully. A page that looks correct in a browser can lose styles or images when opened from a different working directory or when an asset is outside the permitted path.
Set the viewport and output dimensions
The image manual distinguishes the screen dimensions used for rendering from the final crop. The most useful controls are:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →| Option | Effect | Important qualification |
|---|---|---|
--width <pixels> |
Guides the page’s screen width. | The manual describes this as a guideline unless strict-width behavior is requested by the build. |
--height <pixels> |
Sets the screen height. | Without an explicit height, height is calculated from page content. |
--crop-x <pixels> |
Sets the crop’s left coordinate. | Use with the other crop coordinates for a predictable rectangle. |
--crop-y <pixels> |
Sets the crop’s top coordinate. | Coordinates are based on the rendered page. |
--crop-w <pixels> |
Sets crop width. | Do not confuse it with viewport width. |
--crop-h <pixels> |
Sets crop height. | Do not confuse it with viewport height. |
For a desktop-style render with a fixed viewport:
wkhtmltoimage --width 1440 --height 900 https://example.com desktop.pngFor a 1200-by-800 region beginning 40 pixels from the left and 120 pixels from the top:
wkhtmltoimage --width 1440 --height 900
--crop-x 40 --crop-y 120 --crop-w 1200 --crop-h 800
https://example.com region.pngRender first, inspect the result, and then adjust the crop. Responsive breakpoints can move content when the width changes, so a crop that works at one width may miss content at another.
Rank #3
Wait for JavaScript-driven content
JavaScript is enabled by default. A page can still be captured before its data, charts, or deferred images are ready. Choose a wait strategy that matches the page:
Use a fixed delay when timing is predictable
wkhtmltoimage --javascript-delay 3000 https://example.com/dashboard dashboard.pngThe value is in milliseconds. Increase it only as much as needed; a long delay increases job time without guaranteeing that a failed request will recover.
Use a window-status signal when the page can cooperate
If the page sets window.status to a known value after rendering, wait for that value:
wkhtmltoimage --window-status ready https://example.com/report report.pngThis is usually more deterministic than guessing a delay, but it requires control of the page or documentation from its developer. Neither method promises browser-identical rendering for every interactive site.
Disable scripts for a static diagnostic capture
wkhtmltoimage --disable-javascript https://example.com static-only.pngThis can help identify whether a blank or partially rendered image is caused by scripts. It also intentionally removes content that depends on JavaScript.
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
Pass cookies, headers, and other request details
Authenticated pages may require the same request context as a browser session. The image manual exposes cookie and custom-header options:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
wkhtmltoimage
--cookie session_id abc123
--custom-header Authorization "Bearer TOKEN"
https://example.com/account account.pngUse the exact cookie names and header values expected by the site. Avoid placing secrets directly in shell history or shared process lists; prefer an environment-variable strategy supported by your job runner, and restrict permissions on scripts containing credentials. A header can authenticate the initial request while JavaScript subsequently makes separate requests that need their own authentication.
A repeatable capture workflow
- Define the deliverable. Decide whether you need an image or a PDF, the target format, viewport width, height, and any crop rectangle.
- Verify the binary. Record
wkhtmltoimage --versionand inspect--helpon the machine that will run the job. - Capture without extra options. Establish that the URL or local file is reachable.
- Stabilize page timing. Add
--javascript-delayor--window-statusonly when the initial image shows incomplete content. - Set the viewport. Add
--widthand, if required,--height. Recheck responsive layout changes. - Crop last. Apply crop coordinates after the full rendered framing is correct.
- Validate the artifact. Check file type, dimensions, visual completeness, and whether remote assets loaded.
- Log failures. Save stderr, the command parameters (without secrets), executable version, URL, and output path for reproducibility.
Troubleshoot common failures
| Symptom | Likely cause | Fix |
|---|---|---|
wkhtmltoimage: command not found |
The image companion is not installed or is outside PATH. |
Install a package containing wkhtmltoimage, call its absolute path, and rerun --version. |
| A PDF is produced when an image was expected | wkhtmltopdf was invoked. |
Replace it with wkhtmltoimage; use --format or an image extension. |
| Blank page or missing content | Scripts, network requests, bot checks, or delayed rendering did not complete. | Inspect stderr, try a controlled JavaScript delay or window-status wait, and test the URL directly from the capture host. A delay cannot fix a blocked or failed request. |
| Charts or data are absent | Capture occurred before JavaScript finished. | Use --javascript-delay or arrange a page-side window.status signal. Confirm that the data endpoint is reachable from the same host. |
| Styles, fonts, or images disappear from local HTML | Relative paths or local-file restrictions prevent asset loading. | Use an explicit input path, verify relative URLs, allow the required directory, or keep local access disabled and copy only needed assets into an allowed folder. |
| The width is not exact | --width is a rendering guideline in the documented behavior. |
Check your build’s strict-width support, inspect the actual output dimensions, and use cropping for the final rectangle. |
| Authenticated content is missing | Cookies or headers were not supplied, expired, or do not apply to later requests. | Pass the required --cookie and --custom-header values, verify their scope, and remove secrets from logs. |
| Output differs between machines | Different packaged builds, fonts, Qt behavior, or page timing. | Pin the executable and environment where possible, record the version, and validate representative pages after upgrades. |
Reliability, security, and maintenance considerations
Rendering fidelity
wkhtmltoimage uses Qt WebKit rather than a current mainstream browser engine. The documented options cover timing, dimensions, cookies, headers, and local access, but they do not guarantee pixel parity with modern browser releases. Treat complex single-page applications, newer CSS, Web Components, and anti-automation pages as compatibility tests, not assumptions.
Headless operation
The project explicitly states that the utilities run entirely headless and do not require a display or display service. That makes them suitable for command-line jobs and servers, subject to the permissions and network access of the account running the process.
Archived project status
The repository is archived and read-only. Confirm the exact binary, build options, and security policy used by your operating system or container image. Do not assume that an option documented for one package exists in another.
Recommended Free Tools
Protect inputs and credentials
A URL, cookie, header, or local-file permission can grant access to sensitive data. Restrict who can submit capture jobs, avoid logging tokens, limit --allow paths, and keep output files private when the page contains authenticated information.
Or skip the browser setup
If you need a maintained HTTP workflow instead of managing a Qt WebKit executable, ScreenshotNeo returns a webpage image or PDF from one request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and the response identifies the result with X-Page-Verdict and X-Billed headers. It also provides an MCP server for AI clients such as Claude and Cursor, with take_screenshot, get_page_info, and capture_pdf tools.
The API supports full-page captures with lazy images loaded, CSS-selector element capture, dark mode, device presets or custom viewports, retina scale, PDF paper and page controls, custom CSS and JavaScript, click and wait actions, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed image links, asynchronous signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work, easing migration.
See the ScreenshotNeo documentation for request details. A minimal image request is:
Free tools Windows power users keep installed
One-click scans. No signup required.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe equivalent Python and Node.js calls are:
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)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 the API without a card.
Bottom line
For an image, run wkhtmltoimage and reserve wkhtmltopdf for PDF output. Start with a plain URL command, then add viewport dimensions, waits, crops, cookies, headers, or local-file permissions one at a time. Because the project is archived and based on Qt WebKit, verify the output against the sites you actually need to capture; use a browser-based API when modern rendering, consent cleanup, billing visibility, or AI-agent access matters more than a local command.
Frequently Asked Questions
Can I use the same command for a local HTML file and a URL?
Yes. The documented input position accepts either a URL or an HTML file path; local files may additionally need explicit asset permissions such as --allow.
Should I prefer a delay or a window-status wait?
Use a fixed delay when the page’s rendering time is predictable. Use --window-status when the page can set a known completion value; it avoids guessing a duration but requires page cooperation.
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.
