How to Install wkhtmltoimage on macOS with Homebrew

Short answer: A Homebrew formula for wkhtmltoimage or wkhtmltopdf was not confirmed in the current Homebrew core formula search. Do not rely on brew install wkhtmltoimage or brew install wkhtmltopdf as verified commands. The wkhtmltopdf project lists a 64-bit macOS installer for its 0.12.6 stable series, released June 11, 2020. Check whether that installer supports your macOS version and Mac architecture before installing it.

wkhtmltoimage is an open-source command-line HTML-to-image renderer that uses Qt WebKit. The project’s downloads page also warns against processing untrusted HTML or JavaScript without sanitizing it. See the wkhtmltopdf project and its official downloads page.

1. Check your Mac and Homebrew

Open Terminal and identify your hardware and macOS version:

uname -m
sw_vers -productVersion

arm64 indicates Apple Silicon; x86_64 indicates Intel. Homebrew’s default prefix is /opt/homebrew on Apple Silicon and /usr/local on Intel. These are Homebrew paths, not a guarantee that the older wkhtmltoimage installer supports either machine.

Check whether Homebrew is installed and which prefix it uses:

brew --version
brew --prefix

If brew is not found, follow Homebrew’s official installation instructions. Homebrew’s documented current requirements describe Apple Silicon as its supported CPU configuration and Intel as Tier 3; check its documentation for current macOS requirements. Formulae built from source require Xcode or the Xcode Command Line Tools.

2. Check Homebrew for a formula

Search Homebrew’s current formula directory or query it from Terminal:

brew search wkhtmltoimage
brew search wkhtmltopdf

A search result alone may include casks, taps, or other entries. Check the current Homebrew Formulae directory for a matching core formula. The available research did not identify a core formula page for either executable. This does not rule out third-party taps or local formulae, but none is established here as a verified route.

If no suitable formula appears, do not guess a tap name or install command. Continue with the official project download route below.

3. Use the project-listed macOS installer if compatible

Open the official downloads page.
Review the macOS 64-bit installer listed for the 0.12.6 stable series. The page dates that series to June 11, 2020.
Read the installer’s stated requirements and assess them against your exact macOS release and CPU. The historical installer listing is not a current compatibility guarantee.
Download and run the installer only if its source and requirements are suitable for your machine. Follow the installer’s prompts.
Open a new Terminal window and verify that the executable is available.

No installation or compatibility test is implied by these instructions. The project’s listing does not establish support for every current macOS version or Apple Silicon configuration.

4. Verify the executable and render a page

Check that the command resolves and print its version:

command -v wkhtmltoimage
wkhtmltoimage --version

If the command is found, try a simple public page and save a PNG:

wkhtmltoimage https://example.com example.png

To capture a local HTML file instead, pass its path as the input:

wkhtmltoimage ./page.html example.png

For a quick HTML-to-image conversion, that is enough to confirm the command is callable. Rendering details can vary with the page, its external resources, and this older Qt WebKit-based renderer.

5. If the executable is installed but missing from PATH

command -v wkhtmltoimage prints the executable path when the shell can find it. If it prints nothing, inspect the installer’s documented destination and add that directory to your shell’s PATH. Do not assume the Homebrew prefix is where a standalone project installer placed the file.

For example, if you have verified that the executable is in /path/to/bin, add that directory to your shell configuration. For zsh, commonly the default shell on macOS:

echo 'export PATH="/path/to/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
command -v wkhtmltoimage
wkhtmltoimage --version

Replace /path/to/bin with the actual directory. This edits your zsh configuration; if you use another shell, update that shell’s startup file instead.

Options and practical limits

The installation research establishes the macOS installer listing and Homebrew search caveat, not a complete inventory of renderer flags. Once installed, inspect the version’s own help for supported options:

wkhtmltoimage --help

Do not assume modern browser behavior: wkhtmltoimage uses Qt WebKit, and the listed stable series dates to 2020. Test important layouts, scripts, fonts, and remote assets on the exact machine and version where you plan to run it.

Security, reliability, and cost

Security: The project explicitly warns that untrusted HTML or JavaScript can lead to a complete server takeover. Sanitize user-supplied content and do not render arbitrary input in a privileged environment.
Reliability: The project-listed installer is old. Verify compatibility and output on your target macOS release rather than treating the download listing as proof of current support.
Performance: No benchmark is established here. Rendering time depends on the page and its resources; measure representative pages in your own environment before sizing a workload.
Cost: The research does not establish a price for the installer. Check the project’s current distribution terms and any deployment requirements.

Common errors and fixes

Symptom	Likely cause	What to do
`No formula found` or Homebrew cannot install the package	No matching current core formula was confirmed.	Search the formula directory and the official project downloads. Do not rely on an unverified `brew install` command.
`command not found: wkhtmltoimage`	The installer did not add its directory to PATH, or installation did not complete.	Check the installer’s destination, inspect the executable there, and add the verified directory to PATH.
Installer will not run or the command fails on launch	Possible macOS or CPU incompatibility, or an installer issue.	Compare your system details with the installer’s stated requirements and consult the project release information. The old listing does not promise support for your current system.
Image is blank or missing page content	The page may depend on resources or rendering behavior unavailable to this older engine.	Try a simple page, check that the source is reachable, then test the target page’s scripts and remote assets. Verify the output on the same version and machine you will use.
Unexpected output from user-provided HTML	Rendering untrusted HTML or JavaScript is unsafe.	Sanitize input and isolate rendering. Follow the project’s security warning before processing user-supplied content.

Or skip the browser setup

If your goal is to capture a website as an image, ScreenshotNeo provides a website screenshot API and MCP server for developers. Make a GET request with a URL to receive a PNG, JPEG, WebP, or PDF. Its cookie and consent banner handling removes supported consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf.

For a one-call WebP capture, see the ScreenshotNeo API documentation and use your API key:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

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}`);

ScreenshotNeo includes 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000 screenshots. Sign up for the free plan.

FAQ

Can I install wkhtmltoimage with Homebrew?

A current Homebrew core formula was not confirmed in the research for this guide. Check Homebrew’s formula directory and search results on your machine before choosing an installation route.

Is wkhtmltoimage the same as wkhtmltopdf?

They are related command-line tools in the wkhtmltopdf project. This guide covers the image-rendering executable; the project download page also lists the companion PDF tool.

Does the official macOS installer support Apple Silicon and current macOS?

The project lists a 64-bit macOS installer for its 0.12.6 stable series, but that historical listing does not establish compatibility with every current macOS release or Apple Silicon Mac. Verify on your machine before relying on it.

How do I know installation worked?

Run command -v wkhtmltoimage and wkhtmltoimage --version. Then render a simple page and inspect the output file.