wkhtmltoimage is a headless command-line tool that renders a web page or local HTML file as an image. Install a release asset that matches your operating system and CPU architecture, verify the installed binary, then run wkhtmltoimage [OPTIONS] input output. The project’s downloads page identifies 0.12.6, released June 11, 2020, as its stable series, but its platform list is historical guidance—not a guarantee that an asset is still available or compatible with your system. The project repository was archived in January 2023, a significant consideration if you need a renderer with ongoing browser-engine security maintenance.
What wkhtmltoimage does
wkhtmltoimage converts HTML into an image using the Qt WebKit rendering engine. It can accept a URL or an HTML file, and it runs headlessly, so it does not require a display service. The output file extension selects the image format; confirm which formats your particular build supports in its help output or manual.
The basic command shape is:
wkhtmltoimage [OPTIONS]... <input file> <output file>The project’s published downloads page names version 0.12.6 as its stable series and gives June 11, 2020, as its release date. The project repository was archived on January 2, 2023, and is read-only. That does not prevent an existing binary from running, but it matters when choosing a renderer for a system that needs ongoing browser-engine security updates.
Install a build that matches your system
Use the project’s release assets rather than assuming a single package-manager command applies everywhere. The downloads page historically listed a Windows installer or archive, a macOS installer, and Debian 11 packages for several architectures. Because that published platform information is old, check the current release assets directly for your operating system and CPU architecture, and verify dependencies before installing.
Recommended Free Tools
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
- Identify your platform. Note the operating-system version and CPU architecture. Choose an asset that matches both; a package built for a different architecture or distribution may not install or run correctly.
- Check the release asset and its dependencies. Confirm that the asset is still available and read any platform-specific notes. Do not assume that a package listed historically remains compatible with newer releases of the same operating system.
- Install using the method appropriate to that asset. Follow its installer or package instructions. Exact steps vary by operating system, release, and package format.
- Verify the executable. Run
wkhtmltoimage --version. If the shell cannot find the command, check that installation completed and that the executable’s directory is on yourPATH. - Inspect the options available in your build. Run
wkhtmltoimage --help; usewkhtmltoimage --extended-helpor the installed manpage for more detail. Defaults and behavior can differ between builds.
Build choice can affect rendering behavior: the project notes that some features require patched Qt. If an option appears unsupported or behaves differently from the manual, check the installed build’s documentation and package notes rather than assuming every distribution’s binary is equivalent.
Convert a URL or local HTML file
Capture a web page
wkhtmltoimage https://example.com page.pngThe URL is the input and the filename extension selects the requested output format. These are syntax examples, not a guarantee that every remote site will render successfully: loading can depend on network access, page behavior, and the installed build.
Convert a local HTML file
wkhtmltoimage ./page.html page.pngUse a path to the HTML file as the input. A local page may refer to other local files, such as stylesheets or images. Access to those files is affected by the local-file access settings and the build’s behavior; see the security section before enabling broader access.
Choose an output format
The output filename’s extension is used to select an image format. For example, the examples above request PNG. Consult wkhtmltoimage --extended-help or your installed manual to see the formats supported by your binary and the options it exposes. Do not infer support for a format solely from another build’s documentation.
Free tools Windows power users keep installed
One-click scans. No signup required.
Set capture size, quality, and page timing
Control the viewport width
--width <int> sets the screen width. The Debian unstable manpage describes it as a guideline; --disable-smart-width makes the width strict. If the result’s layout differs from what you expected, check both the selected width and whether smart width is enabled in your build.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
wkhtmltoimage --width 1280 https://example.com page.pngThat command requests a width of 1280; the effective behavior still depends on the binary’s available options and rendering behavior.
Adjust image quality
--quality <int> sets output quality on a scale from 0 to 100, as documented in the Debian manpage. Whether the setting applies as expected depends on the selected output format and build. Check the local help before relying on a particular result.
wkhtmltoimage --quality 85 https://example.com page.jpgWait for JavaScript-driven content
--javascript-delay <msec> waits before rendering. The Debian unstable manpage documents a default of 200 milliseconds. Increasing the delay can give a page more time to update, but it is a fixed wait rather than proof that all page activity has finished.
wkhtmltoimage --javascript-delay 1500 https://example.com page.pngIf the page exposes a useful status value, --window-status <value> waits until window.status equals that value. The page must actually set that status; otherwise, the wait condition may not be reached. Check the installed binary’s manual for the exact behavior and any failure handling in your build.
Handle load failures and local-file access
Choose what happens when a page fails to load
--load-error-handling controls the response to a page-load failure. The documented values include abort, ignore, and skip. Select a mode deliberately: continuing after an error can produce an output that is incomplete, while aborting makes the failure explicit. Consult the installed manual for the exact semantics and default for your build.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Limit access to local files
--disable-local-file-access blocks a local input page from reading other local files unless they are permitted. --allow <path> permits specified paths. If local images or stylesheets do not appear, check whether the page needs access to those files and allow only the required paths where appropriate.
wkhtmltoimage --disable-local-file-access --allow ./assets ./page.html page.pngConfirm path handling with your installed build’s help. Treat permissions as a security boundary: do not grant access to broad directories when a narrower path will do.
Security and maintenance considerations
The wkhtmltopdf 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!” The wording names wkhtmltopdf; it is a project-level warning about the tool family, not a quote that specifically names wkhtmltoimage. For server-side image generation, treat untrusted HTML and JavaScript as hostile input: sanitize it and isolate the renderer where appropriate.
The project’s status discussion identifies its dependence on WebKit1 and raises WebKit security and maintenance limitations. Combined with the repository’s archived status, this makes build provenance and exposure important deployment decisions. A successful capture does not establish that a renderer is suitable for processing arbitrary public input or for a security-sensitive service.
- Prefer a build that matches the target operating system and architecture, and understand which Qt build it uses.
- Do not process untrusted HTML or scripts without sanitization and suitable isolation.
- Limit local-file access to what the capture needs.
- Check the project’s current release assets and your operating system’s dependency requirements before deployment.
Troubleshoot common problems
“command not found” or executable not found
The binary may not have installed, or its directory may not be on the shell’s PATH. Verify the installation location and invoke the executable by its full path to distinguish a missing installation from a path configuration problem.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
The package will not install or the binary will not start
Check that the asset matches the operating system version and CPU architecture. Then review its dependency requirements. The project’s older platform list is not a compatibility guarantee for current operating systems; use the release asset’s notes and the local system’s package information.
The page loads, but the image is blank or incomplete
Check that the URL is reachable from the machine running the command, then inspect any load errors. If the page fills in with JavaScript, try a suitable --javascript-delay, or use --window-status only if the page sets the expected status value. A longer delay cannot fix an unreachable page or a failed resource.
Local images or stylesheets are missing
For local HTML, check that referenced files exist at the paths the page expects. Then inspect the local-file access settings: --disable-local-file-access blocks access unless a path is allowed with --allow. Grant access narrowly and only when required.
The output dimensions or quality are unexpected
Check the output extension, the requested --width, whether smart width is enabled, and the quality option where relevant. Since builds differ, use --extended-help or the installed manpage to verify accepted values and defaults.
An option from an online example is rejected
That option may not be supported by your binary, or its behavior may depend on a patched Qt build. Compare the example with wkhtmltoimage --help and the installed manual, and check the release asset’s build notes.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Performance, reliability, and cost
Rendering cost and speed depend on the page, network access, chosen delay, output format, and installed build; the available project guidance does not establish a universal runtime or resource figure. For repeatable captures, keep the input and viewport consistent, avoid unnecessarily long fixed delays, and record the binary version and relevant options alongside generated images. When a capture is missing content, diagnose load conditions and timing before increasing waits indiscriminately.
For a deployment, consider the maintenance burden as well as whether a local binary works on a test page. The archived repository and WebKit1 limitations are material when ongoing security updates matter. Do not treat a successful local test as evidence of current browser-engine coverage or safety for arbitrary input.
Or skip the browser setup
If you would rather make a screenshot request without installing and maintaining a browser binary, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request can return a PNG, JPEG, WebP, or PDF. For example, save a web page as WebP with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo documentation for API details. Cookie and consent banners are accepted like a visitor and removed along with supported newsletter popups and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots.
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 minuteSign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
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.
