Recommended Free Tools
Run wkhtmltoimage in Docker by using an image that contains the executable, its runtime libraries, and fonts, then bind-mount a working directory so the container can read the input and write the result. The tool runs headlessly, so an X server is not required. The command below is an illustrative adaptation of the documented CLI and Docker volume pattern; it has not been tested as a particular image-and-version combination.
What you need before running it
wkhtmltoimage converts a web page or HTML file into an image. It belongs to the wkhtmltopdf project and uses Qt WebKit. The upstream project says it runs headlessly, so you do not need to install or start an X server in the container. See the upstream project overview.
- Docker installed and able to pull or build the image you choose.
- A container image with
wkhtmltoimage, compatible shared libraries, and fonts installed. - An input URL or an HTML file available to the container.
- A host directory mounted into the container for files you want to read or keep.
The key distinction is between host paths and container paths: after mounting a host directory at /work, the command inside Docker must refer to /work/input.html and /work/output.png, not to the host’s absolute path.
Choose and pin an image
The upstream source repository was archived on January 2, 2023, and its packaging repository on August 28, 2023. The packaging releases page lists 0.12.6.1 r3 as its latest release, with assets dated May 2023; the main project’s 0.12.6 release is dated June 10, 2020. These dates do not establish that a given third-party Docker image is maintained or suitable for your application. Check the upstream releases and packaging releases before selecting a build.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
For a repeatable deployment, use an image you can inspect and trust, and pin a specific tag or digest instead of relying on a moving latest tag. Verify its base distribution, processor architecture, wkhtmltoimage version, and whether it contains the patched-Qt build your application requires. Docker recommends trusted images, including Docker Official Images, and cautions against untrusted images and Dockerfiles in its security guidance.
A community image such as minidocks/wkhtmltopdf can illustrate how to mount a directory, but its Docker Hub page reported an update more than two years before it was crawled. That alone does not establish present maintenance, trustworthiness, or compatibility. Inspect the image’s source, tag, and digest before using it.
Run a conversion with a mounted folder
From the directory containing input.html, use this command skeleton, replacing <pinned-image> with the exact image reference you have selected:
docker run --rm
-v "$PWD:/work"
-w /work
<pinned-image>
wkhtmltoimage input.html output.pngThe mount makes the current host directory available at /work; -w /work sets the container’s working directory; and --rm removes the stopped container. On success, look for output.png in the host directory. This command is an illustrative adaptation of the Docker Hub mount pattern and the documented command form, not a tested invocation against a named image.
Capture a URL directly
The CLI syntax is wkhtmltoimage [OPTIONS]... <input file> <output file>. A URL can be used as the input, for example:
docker run --rm
-v "$PWD:/work"
-w /work
<pinned-image>
wkhtmltoimage https://example.com /work/page.pngReplace https://example.com with the page you are authorized to capture. The output path is in the mounted directory, so it persists after the container exits. The command-line interface and options are documented in the Debian wkhtmltoimage manual.
Check the executable and result
When a command fails, separate image problems from input, permission, or rendering problems. First check whether the image actually includes the executable and which version it runs:
docker run --rm <pinned-image> wkhtmltoimage --versionThen run the conversion and check the host directory for the output. If the container exits successfully but no file appears, confirm that the destination is under the mounted path and that the host directory is writable by the container’s user.
Build or prepare an image with the required dependencies
A minimal base image may not include the shared libraries or fonts needed to render. The archived upstream Debian package manifest names dependencies including fontconfig, FreeType, JPEG and PNG libraries, OpenSSL, X11 libraries, xfonts packages, and zlib. This is a reference for that Debian packaging, not an install list that applies to every distribution or every build. Consult the manifest for context: packaging/build.yml.
When building your own image, choose a base distribution and architecture that match the wkhtmltoimage binary. Install the runtime packages for that distribution, the selected binary, and fonts appropriate to the languages and visual output you need. Package names differ across distributions; do not copy Debian names into an Alpine or other base image and assume they will work. Keep the Dockerfile and binary source auditable, and pin versions so a rebuild does not silently switch to a different renderer.
The available sources do not establish one universal, tested Dockerfile for every base image. Treat installation instructions as distribution- and build-specific, then verify that the binary launches in the final runtime image—not just in a build stage—and that the image can render representative pages from your application.
Load local HTML, images, and stylesheets safely
Mount only the files the conversion needs. If an HTML document refers to local stylesheets, images, or other assets, those files must also be visible at the corresponding paths inside the container. A host path that is not mounted will not become available simply because it appears in the HTML.
Local-file access is security-sensitive. The Debian CLI manual documents --allow <path> to permit access to files in a specified folder, and the upstream 0.12.6 release notes identify blocking local filesystem access by default as a breaking change. If the selected build requires an explicit allowance, grant it narrowly, for example:
wkhtmltoimage --allow /work/assets /work/input.html /work/output.pngUse container paths in the allowance, keep the permitted directory limited to required assets, and avoid mounting secrets or unrelated host directories. Exact behavior can vary with the binary and build you chose, so validate local-resource loading using that build’s manual and a test document.
Useful rendering options
The manual supports options for controlling image output and how the page is loaded. Check the selected build’s own help or manual because an option available in one package may not behave identically in another. Common tasks include:
- Selecting an output format: use an output filename with the image format you need, such as
.pngor.jpg, and confirm that your chosen build supports it. - Setting viewport or rendering dimensions: use the relevant width and height options documented by the CLI when a consistent viewport matters. A full-page result and a fixed viewport can produce different output dimensions.
- Waiting for page content: pages that populate after initial navigation may need an appropriate delay or other load behavior supported by the selected version. Do not assume a delayed or interactive modern page will render like it does in a current browser.
- Passing input-specific settings: consult the CLI options reference for available flags rather than guessing option names.
Keep an eye on resource use when capturing very long pages or running many conversions concurrently: each container process needs CPU and memory, and output size depends on the page and chosen dimensions. The supplied project material does not establish performance figures or concurrency limits, so benchmark representative workloads in your own environment before setting production capacity.
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 →Common failures and how to fix them
“wkhtmltoimage: not found”
The image may not contain the executable, it may be installed under a different path, or the command may be running in a different stage than the one with the binary. Check the selected image with wkhtmltoimage --version, inspect its build instructions, and invoke the correct executable in the final runtime image.
Missing shared library or loader errors
The binary’s runtime dependencies are absent or incompatible with the base image. Recheck the selected distribution and architecture, install the matching runtime libraries, and test inside the final image. The Debian manifest is a useful clue for Debian packaging but is not a cross-distribution package recipe.
Output file is missing or permission is denied
Confirm the output path is inside the bind-mounted directory and that the container user can write there. Use the path as seen inside Docker, not a host-only path. Check ownership and permissions of the host folder if a non-root container user is configured.
Local images or stylesheets do not load
Ensure the asset directory is mounted and the HTML points to the correct in-container paths. Check whether the chosen build requires --allow for local access; limit that allowance to the assets folder rather than opening the whole filesystem.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows 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 reinstallBest Value
Fonts are missing or the image looks different
Install appropriate fonts and fontconfig support for the chosen distribution, then test the actual languages and page styles your application uses. The archived dependency manifest names font and FreeType components, but it does not prescribe a universal font set.
Modern site content is absent or broken
wkhtmltoimage uses Qt WebKit and is a legacy renderer. Its upstream repositories are archived, and the source set does not establish broad compatibility with current web standards. If pages rely on newer JavaScript, layout, or browser APIs, test those pages explicitly and choose a rendering approach that meets the application’s requirements if this one does not.
Container fails before rendering
Check the image tag or digest, processor architecture, Docker pull/build output, and whether the binary is compatible with the image’s system libraries. Avoid assuming that a community image is current simply because it is available in a registry; inspect its provenance and update history.
Or skip the browser setup
If you need a screenshot endpoint rather than maintaining a legacy renderer inside a container, ScreenshotNeo is a website screenshot API and MCP server. One GET request takes a URL and returns an image or PDF. Its clean-shot steps accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each 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 AI agents and MCP clients. There is a free allowance of 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://example.com
-o shot.webpGet an access key by signing up for ScreenshotNeo; the free plan includes 1,000 screenshots a month with no card.
FAQ
Does wkhtmltoimage need a display in Docker?
No. The upstream project describes it as headless, so a display server is not required.
Where does Docker save the screenshot?
It is written to the path you pass as the output argument. To keep it after the container exits, write it inside a host directory mounted into the container.
Is wkhtmltoimage actively maintained?
The upstream source and packaging repositories are archived, with the dates and latest listed packaging release noted above. Do not assume new upstream fixes are being issued.
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 errorsQuick 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.
