Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use the input URL or HTML file as the first positional argument and the image filename as the second:
wkhtmltoimage https://example.com capture.png
wkhtmltoimage is a headless command-line renderer based on Qt WebKit. It can save a remote URL or local HTML document as PNG, JPEG, or another supported image format, while options control viewport size, timing, cropping, scaling, cookies, headers, and local-file access. Its WebKit engine is older than the browser engines used by many current sites, so treat timing and compatibility settings as controls to tune—not as a guarantee of modern-browser fidelity.
What wkhtmltoimage does
The wkhtmltopdf project describes wkhtmltopdf and wkhtmltoimage as “open source (LGPLv3) command line tools to render HTML into PDF and various image formats using the Qt WebKit rendering engine.” The image command runs without a display service and accepts either a URL or a local HTML file.
Recommended Free Tools
The general form is:
wkhtmltoimage [OPTIONS]... <input file> <output file>
Options must come before the input and output paths. The output extension normally selects the format, or you can set it explicitly with --format.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Install and verify the binary
Obtain a build
The official workflow is to download a precompiled binary for your operating system or build the project from source, then place the executable somewhere on your PATH. Package names and build behavior differ by distribution. Ubuntu Noble’s manpage identifies package version 0.12.6-2build2; that is an Ubuntu package identifier, not a universal wkhtmltoimage version.
Check the installed program
wkhtmltoimage --version wkhtmltoimage --help
Keep the reported version with your deployment notes. The upstream GitHub repository is archived (the repository status is dated January 2, 2023), so checking the binary and its help output is especially important when moving between operating systems.
Take a basic URL screenshot
Save a PNG
wkhtmltoimage https://example.com capture.png
This uses the documented positional-argument syntax. The command is a syntax example; the resulting pixels depend on the page, network response, installed build, and rendering environment.
Choose JPEG or another format
wkhtmltoimage --format jpg --quality 85 https://example.com capture.jpg
--quality accepts an integer from 0 to 100 for JPEG output. There is no universally correct quality value; choose one that meets your file-size and visual requirements. Use the extension or --format consistently so downstream jobs know what they received.
Render a local HTML document
Basic local input
wkhtmltoimage report.html report.png
A local document may reference stylesheets, fonts, images, or scripts with local paths. Whether those resources load depends on the local-file security settings of your build.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
Permit only required local paths
wkhtmltoimage --enable-local-file-access --allow /srv/report-assets report.html report.png
The manpage documents --enable-local-file-access, --disable-local-file-access, and repeatable --allow <path>. Allow the smallest directory that contains the dependencies, and verify the behavior of the installed build. Do not broadly expose unrelated filesystem paths just to make a missing asset appear.
Control viewport size and page geometry
Set the screen dimensions
wkhtmltoimage --width 1440 --height 900 https://example.com desktop.png
--width sets screen width as a rendering guide. --height sets screen height; the default height is calculated from page content. If you need a strict width, disable smart width as documented by the manpage:
Free tools Windows power users keep installed
One-click scans. No signup required.
wkhtmltoimage --width 1280 --disable-smart-width https://example.com fixed-width.png
Responsive breakpoints can change when width changes. Record the width and height alongside each capture if screenshots are used for visual regression.
Crop a region
wkhtmltoimage --crop-x 100 --crop-y 200 --crop-w 800 --crop-h 600 https://example.com region.png
--crop-x and --crop-y select the starting coordinates; --crop-w and --crop-h set the crop dimensions. Cropping is geometric, not a CSS selector: the coordinates refer to the rendered page.
Scale the render
wkhtmltoimage --zoom 1.25 https://example.com enlarged.png
--zoom <float> adjusts scale. Combine it deliberately with viewport dimensions because changing either value can alter line wrapping and the resulting crop.
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
Wait for JavaScript and dynamic content
Use a fixed delay
wkhtmltoimage --javascript-delay 2000 https://example.com dynamic.png
--javascript-delay <msec> waits the specified number of milliseconds after loading. A delay can help with predictable, short client-side initialization, but it cannot guarantee that every asynchronous request has completed.
Wait for a window status value
Pages you control can set a status value when they finish preparing content. Match it with:
wkhtmltoimage --window-status ready-for-shot https://example.com dynamic.png
This is useful when page code can signal readiness. It still depends on the page setting the expected value and on what the Qt WebKit engine supports.
Understand the compatibility boundary
JavaScript can be enabled or disabled, but wkhtmltoimage’s Qt WebKit engine is not a current Chromium, Firefox, or WebKit release. Modern syntax, APIs, cross-origin behavior, lazy loading, and bot defenses may render differently or fail. If a page requires a current browser engine, test representative pages before making the tool part of an automated pipeline.
Pass cookies, headers, and protected-page settings
The manpage documents options for cookies, custom HTTP headers, authentication, proxies, and client certificates. Use those options when a page requires a session or non-default request metadata. Keep credentials out of shell history where possible, restrict log access, and prefer short-lived tokens. For a reproducible job, record which cookies, headers, proxy, and certificate settings were used without logging secret values.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
Diagnose failed or incomplete captures
The command is not found
- Confirm that the executable exists and is on
PATH. - Run
wkhtmltoimage --versionwith the same user and environment as the job. - Use the absolute executable path in a service or container if its environment differs from your interactive shell.
The output is blank or an error page
- Run with a diagnostic log level and inspect the page-loading message:
wkhtmltoimage --log-level info --load-error-handling abort https://example.com capture.png
The manpage also documents --debug-javascript and --load-media-error-handling. Use them to distinguish script errors, navigation failures, and media failures. A blank result can also indicate that the site requires browser features unavailable in Qt WebKit.
Images or styles are missing from local HTML
- Check that referenced paths exist from the process’s working directory.
- Use
--enable-local-file-accessand a narrowly scoped--allowpath when local dependencies are intentional. - Confirm that the installed build has the local-file behavior you expect.
Content is cut off
- Increase
--heightor remove an overly restrictive crop. - Check whether responsive CSS changed because of
--width. - Use
--zoomto fit content, then verify text remains legible.
The page is captured before it is ready
- Add a measured
--javascript-delay. - Prefer
--window-statuswhen you control the page and can signal readiness. - Do not assume a longer delay fixes unsupported browser APIs or failed network requests.
Build a dependable capture workflow
- Pin the executable. Record the OS, package or binary version, and output format.
- Define the rendering contract. Specify URL or local input, viewport width and height, crop, zoom, and expected assets.
- Make readiness explicit. Use a status signal for pages you control; otherwise choose a delay based on observed page behavior.
- Capture diagnostics. Preserve exit status and relevant log output so a failed image is not mistaken for a valid one.
- Test representative pages. Include pages with scripts, lazy media, authentication, local assets, and responsive layouts before automating at scale.
- Limit access. Restrict local paths, credentials, proxy access, and output-directory permissions to what the job needs.
There is no published performance, usage, or accuracy statistic establishing a universal delay, quality setting, or current-browser equivalence. Treat those values as workload-specific configuration rather than promises.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns PNG, JPEG, WebP, or PDF. Before capture it accepts cookie and 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 response headers identify the page verdict and billing result.
One-call cURL example
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
See the complete option list and authentication details in the ScreenshotNeo documentation.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Python
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}`);
Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. Other options include full-page lazy-image loading, CSS-selector element capture, dark mode, device presets, arbitrary viewports, retina scale, PDF paper and page controls, custom CSS or JavaScript, click-before-capture, selector hiding, selector or network-idle waits, request blocking, headers, cookies, user agent, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTL, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameters used by other screenshot APIs also work to ease migration.
Plans are Free (1,000 shots per month, no card), Starter $5 for 3,000, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000. Yearly billing gives two months free, and every feature is on every plan. Create a free ScreenshotNeo account to get 1,000 screenshots a month without a card.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
FAQ
Can wkhtmltoimage create PDFs?
The related wkhtmltopdf tool creates PDFs; wkhtmltoimage’s job is image output. Use the image command when your target is PNG, JPEG, or another supported image format.
Does a larger delay guarantee a complete page?
No. A delay only waits a specified time. Unsupported browser features, failed requests, or pages that never signal readiness can still produce incomplete output.
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 →Should I enable local-file access globally?
No. Enable it only for workflows that need local resources and pair it with the narrowest necessary --allow paths.
Frequently Asked Questions
Can wkhtmltoimage capture a local HTML file and a remote URL with the same command shape?
Yes. Put either the URL or local HTML path first, followed by the output image path; options come before both positional arguments.
How do I know which wkhtmltoimage build I am running?
Run wkhtmltoimage --version and review wkhtmltoimage --help; distribution package identifiers are not universal.
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.
