Install wkhtmltopdf on macOS with Homebrew

Short answer: Check Homebrew’s live package metadata before installing. Run brew update and brew info wkhtmltopdf. If Homebrew reports an installable formula, follow the command it shows. Formula availability was not confirmed for this guide, so do not assume brew install wkhtmltopdf will work. If no installable formula is available, the official wkhtmltopdf downloads page lists a legacy macOS installer for version 0.12.6.

wkhtmltopdf converts HTML pages to PDF using Qt WebKit. The project also describes headless operation, so it can render without a display service. Its latest listed stable release is 0.12.6, dated June 11, 2020, and its GitHub repository is archived. Consider compatibility and maintenance before choosing it for a new system. Official downloads · Project repository

1. Check your Homebrew setup

Open Terminal and check that Homebrew is on your shell’s path:

brew --version
brew update
brew info wkhtmltopdf

brew info is the key check. Homebrew documents that it explains whether a formula is deprecated or disabled. Those states have different consequences: deprecated packages may still install, while disabled packages cannot be installed; a removed package is no longer in that repository. The live formula lookup and expected core formula path were inconclusive during research, so this guide does not promise the formula exists. See Homebrew’s FAQ and formula lifecycle guidance.

If brew info wkhtmltopdf shows an installable formula, use the install command shown by Homebrew. You can try:

brew install wkhtmltopdf

Then check whether the executable is available:

wkhtmltopdf --version
which wkhtmltopdf

If Homebrew says there is no available formula, or that it is disabled, repeating the same install command will not resolve the formula state. Use the fallback section below or choose a maintained HTML-to-PDF solution that fits your environment.

2. Confirm the Homebrew architecture and shell setup

Homebrew’s documented default prefix is /opt/homebrew on Apple Silicon and /usr/local on Intel Macs. The installer instructs you to add brew shellenv for your actual prefix to your shell configuration. If brew works but an installed command cannot be found, check whether the expected Homebrew directory is configured in your shell startup file. Homebrew installation instructions

uname -m
brew --prefix
brew config

On Apple Silicon, uname -m normally reports arm64; under a Rosetta shell it may report x86_64. If you have both Apple Silicon and Intel Homebrew installations, verify that brew --prefix and which brew refer to the installation you intend to use. Homebrew says bottles and casks on Apple Silicon do not require developer tools. Developer tools are needed to build formulae from source; do not install Xcode preemptively just to try a package install. Intel macOS is a Tier 3 Homebrew configuration, which describes Homebrew support for the host environment and does not guarantee a particular formula works.

3. If no formula is available, assess the official installer

The wkhtmltopdf downloads page lists a 64-bit macOS installer for macOS 10.7 or later, for version 0.12.6. This is an upstream listing, not a guarantee that it works on current macOS releases or Apple Silicon. The release is from 2020 and the repository is archived, so treat it as legacy software.

Open the official wkhtmltopdf downloads page and locate the macOS installer listing.
Review the listed version and platform details for your Mac before downloading.
Follow the installer instructions supplied by the project, then open a new Terminal window and check wkhtmltopdf --version.
If the executable is not found, check the installer’s documentation for its installation location and verify that location is on your PATH.

This route does not provide the Homebrew formula’s package management or update path. Do not assume the old installer is compatible with your current OS or CPU, and do not bypass macOS security protections based on generic advice. If it will not run, use a currently maintained alternative compatible with your deployment target.

4. Verify PDF generation

After installation, use a simple public page as a smoke check:

wkhtmltopdf https://example.com example.pdf

Confirm that example.pdf was created and opens. This verifies that the command can launch and render a basic page; it does not establish compatibility with every site, JavaScript application, font, or current macOS release.

5. Troubleshoot common installation problems

Symptom	Likely cause	What to do
`No available formula`	The formula is absent from the metadata/repository available to your Homebrew installation, or its state changed.	Run `brew update`, then `brew info wkhtmltopdf`. Check Homebrew’s current formula catalog. If it remains unavailable, assess the official legacy installer or select another renderer.
Formula is deprecated	Homebrew has marked the formula for lifecycle action; deprecated and disabled are not the same state.	Read the explanation from `brew info wkhtmltopdf` and Homebrew’s lifecycle documentation. Decide whether the package’s status is acceptable for your use.
Formula is disabled	Homebrew blocks installation of a disabled formula.	Do not keep retrying the install command. Check the stated reason and use a supported alternative if one is needed.
`brew: command not found`	Homebrew is not installed, or its prefix has not been added to the shell environment.	Follow the official installation instructions, including the `brew shellenv` setup for the installed prefix. Open a new shell and check `brew --version`.
`wkhtmltopdf: command not found`	Installation did not complete, or the executable’s directory is not on `PATH`.	Check the install output, run `which wkhtmltopdf`, and verify the relevant installation location against your shell path.
Download or network error	Homebrew could not retrieve required metadata or an artifact.	Keep the exact diagnostic, check your network/proxy configuration, and retry after connectivity is restored. If the message instead reports a missing or disabled formula, treat that as package availability rather than a network failure.
Architecture or OS compatibility error	The available artifact may not support your CPU or macOS version; the upstream installer listing does not establish current compatibility.	Check `uname -m`, `brew --prefix`, and the exact error. Do not assume the listed 64-bit installer is native to Apple Silicon or supported on current macOS. Choose a renderer supported for your target platform if needed.
PDF is blank or incomplete	The command ran, but page loading or rendering did not produce the expected content.	Try a simple page first, then inspect the target page’s loading behavior and the tool’s documented options. The research does not establish a wkhtmltopdf-specific fix for modern sites; do not infer that successful installation guarantees faithful rendering.

When asking for help, include the macOS version, CPU architecture, output of brew --prefix and brew info wkhtmltopdf, the exact command, and the complete error text. This helps distinguish formula lifecycle, shell setup, download, and compatibility problems.

6. Security, reliability, and maintenance

The 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!” Source: official downloads page. Treat untrusted HTML and JavaScript as a serious security boundary, especially when rendering user submissions in a server-side application.

For reliability, pin and document the exact version and installation route used by your team, and validate output on the macOS versions and CPU architectures you deploy to. The old upstream release and archived repository mean you should account for compatibility risk and the absence of an active upstream maintenance path. Avoid assuming a local success proves the same setup will work on a CI runner or production host.

Cost depends on the route: the Homebrew package manager and upstream project are available without a stated purchase price in the cited sources, but installation time, build requirements, maintenance, and compatibility work still have costs. Source builds require Xcode or the Xcode Command Line Tools; Apple Silicon bottles and casks do not require developer tools. The research does not establish whether a wkhtmltopdf formula is currently installable or what its build requirements would be today.

Or skip the browser setup

If your goal is simply to capture a webpage as an image or PDF, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. See the API documentation.

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

Cookie banners are accepted and removed before capture; known consent platforms, newsletter popups, and chat widgets are removed. Each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status.
An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
The Free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

Create a free account and get 1,000 screenshots a month with no card.

FAQ

Does `brew install wkhtmltopdf` work on every Mac?

No. Check current Homebrew metadata with brew info wkhtmltopdf; availability was not confirmed for this guide, and an available formula would not guarantee support for every Mac configuration.

Is the official macOS installer current?

The downloads page lists version 0.12.6, released in 2020, and the project repository is archived. The listing is not proof of current macOS or Apple Silicon compatibility.

Do I need Xcode before trying Homebrew?

No. Homebrew says Apple Silicon users can install bottles and casks without developer tools. Developer tools are required to build formulae from source.

Can I safely render HTML submitted by users?

The project warns that untrusted HTML and JavaScript can create a severe security risk. Sanitize user-supplied content and assess whether this legacy renderer is suitable for your threat model.