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 →imgkit does not render pages by itself. It is a Python wrapper that starts the separate wkhtmltoimage command-line program. Install both components, make sure the executable is discoverable (or provide its full path), then choose from_url, from_file, or from_string for your input.
This guide covers installation, practical Python examples, renderer options, headless servers, failure diagnosis, and an API alternative when maintaining a browser-rendering binary is not useful.
Understand the two components
imgkit is the Python interface. wkhtmltoimage is the renderer that converts HTML through Qt WebKit into an image file. Installing only the Python package leaves you without the executable that actually performs the conversion.
- imgkit: install into your Python environment with
pip install imgkit. - wkhtmltoimage: install the wkhtmltopdf distribution for your operating system; that distribution provides the image-rendering executable.
After installing, verify that running wkhtmltoimage from a terminal works, or note its absolute path for an explicit IMGKit configuration.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
Install and verify imgkit
- Create or activate the virtual environment used by your application.
- Install the wrapper:
python -m pip install imgkit - Install wkhtmltopdf for your operating system, which supplies
wkhtmltoimage. - Check executable discovery by running
wkhtmltoimage --version. If the shell cannot find it, use the configuration shown below.
Keep the Python package and renderer installed in the same deployment image or server provisioning process. A local development installation does not automatically make the binary available in CI, a container, or a production host.
Choose the conversion method
Render a URL
Use from_url when the source is an HTTP or HTTPS page.
import imgkit
imgkit.from_url("https://example.com", "out.jpg")The call returns after wkhtmltoimage finishes. The second argument is the destination path.
Render a local HTML file
Use from_file for a saved document:
import imgkit
imgkit.from_file("page.html", "out.jpg")You can also pass an open file object:
import imgkit
with open("page.html", "rb") as source:
imgkit.from_file(source, "out.jpg")Render an HTML string
Use from_string when your application generates the markup:
import imgkit
html = "<h1>Hello</h1>"
imgkit.from_string(html, "out.jpg")These functions accept False instead of a filename when you want the image bytes in memory:
import imgkit
image_bytes = imgkit.from_string("<h1>Hello</h1>", False)
with open("out.jpg", "wb") as output:
output.write(image_bytes)Set image format and renderer options
Pass wkhtmltoimage command-line settings through an options dictionary. IMGKit option keys omit the command-line -- prefix. A flag that has no value can use None, False, or an empty string. The documented format example is:
import imgkit
options = {
"format": "png"
}
imgkit.from_url("https://example.com", "out.png", options=options)Options are renderer options, so consult the wkhtmltoimage option names supported by the version installed on your host. Values that can occur more than once may be represented as a list or tuple; options accepting multiple values can use a tuple. For example:
options = {
"format": "png",
"custom-header": [("X-Environment", "staging"), ("X-Trace", "capture")]
}
imgkit.from_url("https://example.com", "out.png", options=options)Keep option values typed as the wrapper expects. A renderer flag is not a Python keyword argument; put it inside options.
Configure an explicit wkhtmltoimage path
Automatic PATH lookup is convenient but fragile in services, virtual environments, containers, and Windows installations. Create an IMGKit configuration with the executable’s full path and pass it to the conversion function:
import imgkit
config = imgkit.config(
wkhtmltoimage="/opt/wkhtmltox/bin/wkhtmltoimage"
)
imgkit.from_url(
"https://example.com",
"out.jpg",
config=config
)Replace the example path with the path on your host. The important test is that the path names the executable itself, not merely the directory containing it. If your platform uses a different location, discover it with the operating system’s executable-search tools and then use the resulting absolute path.
Run imgkit on headless servers
The upstream project describes wkhtmltoimage as running entirely headless without a display or display service. IMGKit’s documentation nevertheless notes that some headless server deployments may need Xvfb, a virtual X display.
When to try Xvfb
- The conversion works on your workstation but fails on a server with display-related errors.
- Your server image lacks a display service and the renderer exits before producing a file.
- Your deployment standard already provides a virtual display for other GUI-dependent jobs.
IMGKit exposes an xvfb configuration path. Configure it in the same way as the renderer path when your deployment requires the documented virtual-display setup:
Crashes, 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 minuteWindows 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 reinstallimport imgkit
config = imgkit.config(
wkhtmltoimage="/opt/wkhtmltox/bin/wkhtmltoimage",
xvfb="/usr/bin/xvfb-run"
)
imgkit.from_file("page.html", "out.png", config=config)Do not add Xvfb merely because the job is headless; first test the renderer as installed. Treat it as a deployment-specific remedy for display failures.
Build a reliable conversion function
Production code should make the source, output format, binary path, and timeout policy explicit at the application boundary. A small wrapper also gives you one place to log the input type and renderer errors:
from pathlib import Path
import imgkit
def render_page(source_url: str, output: str, wkhtmltoimage_path: str | None = None) -> None:
config = None
if wkhtmltoimage_path:
config = imgkit.config(wkhtmltoimage=wkhtmltoimage_path)
options = {
"format": Path(output).suffix.lstrip(".") or "png"
}
imgkit.from_url(source_url, output, options=options, config=config)
render_page(
"https://example.com",
"example.png",
"/opt/wkhtmltox/bin/wkhtmltoimage",
)Only use a suffix that your installed renderer supports. If you need a specific format, set it directly instead of deriving it from an untrusted filename.
Troubleshoot common failures
No wkhtmltoimage executable found
Cause: the renderer is not installed or is not on PATH. Fix: install the wkhtmltopdf package that provides it, verify wkhtmltoimage --version, or pass imgkit.config(wkhtmltoimage="/full/path/to/wkhtmltoimage").
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →The Python import fails
Cause: imgkit was installed into a different interpreter or virtual environment. Fix: run python -m pip install imgkit with the same python command that starts your application.
A file is not created
Cause: the source page failed to load, the output directory is not writable, or the renderer exited with an error. Fix: render a minimal local HTML string first, write to a known writable directory, then test the URL. Preserve stderr and the return status from the failing job so you can distinguish source failures from filesystem errors.
The result is blank or incomplete
Cause: the page depends on resources that the renderer cannot load or needs more time before capture. Fix: test a self-contained HTML file, confirm URL access from the deployment host, and pass the appropriate wkhtmltoimage options through options. A local file test separates network and page-loading problems from IMGKit configuration.
Display or X-server errors occur only in production
Cause: this deployment needs a virtual display even though the renderer is designed for headless use. Fix: install and configure Xvfb as documented by IMGKit, then provide its path through the xvfb configuration setting.
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 errorsThe output format is unexpected
Cause: the filename extension and renderer format disagree, or no format was selected. Fix: set "format": "png" (or the format you require) in options and use a matching extension.
Maintenance and deployment considerations
The wkhtmltopdf GitHub repository that contains wkhtmltoimage is marked archived with an archive date of January 2, 2023. Its official changelog lists version 0.12.6 dated June 11, 2020 as the latest release shown there. That maintenance status matters when approving a renderer for a new long-lived system: pin the package you deploy, test representative pages, and keep a migration path if your HTML or security requirements outgrow the renderer.
Run conversion in an isolated worker when inputs are untrusted. Treat remote URLs and custom HTML as network and resource-consuming inputs, restrict outbound access where appropriate, and write outputs to controlled paths. Record the renderer version, source type, options, and failure text so a later reproduction does not depend on a developer’s workstation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If you need an image from a URL without installing a local renderer, ScreenshotNeo provides a GET-based screenshot API. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; those cleanup steps can be disabled individually. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers.
Using the documented API requires an access key. See the ScreenshotNeo API documentation for all options.
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,
)
r.raise_for_status()
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}`);ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. Its 63 options include full-page and selector capture, dark mode, device presets, custom viewports, retina scale, PDF controls, custom CSS and JavaScript, click and wait actions, request blocking, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs also work.
The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing gives two months free. Sign up for the free plan to try it without a card.
Frequently Asked Questions
Can imgkit install wkhtmltoimage for me?
No. IMGKit installs the Python wrapper only; wkhtmltoimage must be installed separately through the wkhtmltopdf distribution.
Can I return image bytes instead of writing a file?
Yes. Pass False as the destination argument and write or stream the returned bytes yourself.
Do all headless deployments require Xvfb?
No. The renderer is described as headless, but IMGKit documents Xvfb for some server setups that still encounter display requirements.
What is the latest wkhtmltoimage release listed by the project?
The official changelog lists version 0.12.6 dated June 11, 2020; the repository is marked archived as of January 2, 2023.
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.
