How to Run wkhtmltoimage with Xvfb on Headless Linux Servers

Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.

Short answer: run wkhtmltoimage directly first. Many current builds render without an X server, but some distribution packages—especially builds using unpatched Qt—still require one. If your binary fails with a display-related error, install Xvfb and invoke it through xvfb-run -a. Verify the behavior of the exact binary and package installed on your server rather than assuming either setup is universal.

What you are installing

wkhtmltoimage is an open-source command-line renderer that uses Qt WebKit to turn a URL or HTML file into an image. Its documented shape is:

wkhtmltoimage [OPTIONS]... <input file> <output file>

A URL can be the input:

wkhtmltoimage https://example.com page.png

For a local document, provide a file path instead:

wkhtmltoimage /var/www/site/index.html page.png

The upstream project describes its tools as headless. In practice, packaging matters: wrapper documentation and a Debian deployment example report that particular builds need an X server and therefore use Xvfb. Treat Xvfb as a compatibility workaround, not an unconditional prerequisite.

1. Check the binary, package and architecture

Before installing anything, identify what your server will execute:

command -v wkhtmltoimage
wkhtmltoimage --version
wkhtmltoimage --help | head -n 40
uname -m
cat /etc/os-release

Record the path printed by command -v. A system package, a manually downloaded release, and a binary placed in an application directory can have different Qt builds and option sets. Ubuntu package versions also vary by release: the Jammy manual documents 0.12.6-2, while the Bionic manual documents 0.12.4-1. Read your binary’s own help output because options and defaults can differ.

The official downloads page lists 0.12.6 as the stable series, released June 11, 2020, along with supported operating systems, distributions and architectures. Check the current downloads information for compatibility before replacing a distribution package.

2. Test whether Xvfb is actually needed

Run a small capture without a display wrapper:

mkdir -p /tmp/wkhtml-test
wkhtmltoimage --width 1280 --height 900 https://example.com /tmp/wkhtml-test/example.png
file /tmp/wkhtml-test/example.png
ls -lh /tmp/wkhtml-test/example.png

A successful command should create a non-empty PNG and return exit status zero. To make the status explicit in a script:

wkhtmltoimage https://example.com /tmp/wkhtml-test/example.png
status=$?
printf 'exit status: %sn' "$status"
test "$status" -eq 0 -a -s /tmp/wkhtml-test/example.png

If the command reports that it cannot connect to a display, exits before rendering, or produces an empty file, test with Xvfb. Do not interpret an ordinary page error, blocked network request or JavaScript failure as proof that an X server is missing; inspect the diagnostic output and HTTP availability separately.

3. Install Xvfb when your build requires it

Ubuntu and Debian

Install the distribution package as root or through sudo:

sudo apt update
sudo apt install xvfb

CentOS, RHEL and compatible systems

IMGKit documents the package name xorg-x11-server-Xvfb for CentOS-family systems:

sudo yum install xorg-x11-server-Xvfb

Package names and repositories differ by release. If a command cannot find the package, use your distribution’s package search and install the Xvfb package supplied for that release instead of copying a package from another distribution.

Confirm both executables

command -v xvfb-run
xvfb-run --help | head -n 20
command -v wkhtmltoimage

IMGKit supports explicit paths for both executables when they are not in PATH. The same principle applies to shell scripts: use absolute paths or set PATH deliberately in services and cron jobs.

4. Run wkhtmltoimage through Xvfb

The usual wrapper form is:

xvfb-run -a wkhtmltoimage https://example.com page.png

-a asks the wrapper to choose an available display number, reducing collisions when several jobs run at once. Use an absolute path if your service account has a restricted environment:

/usr/bin/xvfb-run -a /usr/local/bin/wkhtmltoimage https://example.com /srv/screenshots/example.png

For a local HTML file:

xvfb-run -a wkhtmltoimage /srv/site/index.html /srv/screenshots/index.png

Capture stderr and retain the exit code in automation:

set -o pipefail
xvfb-run -a wkhtmltoimage https://example.com /srv/screenshots/example.png 2>/var/log/wkhtmltoimage.log
status=$?
if [ "$status" -ne 0 ] || [ ! -s /srv/screenshots/example.png ]; then
  echo "wkhtmltoimage failed (status $status)" >&2
  exit "$status"
fi

Xvfb supplies a virtual framebuffer; it does not fix invalid URLs, TLS failures, missing fonts, inaccessible local files or broken page scripts.

5. Select rendering options deliberately

The Ubuntu Jammy manual documents the options below. Confirm availability with wkhtmltoimage --help on your installed build.

Dimensions

wkhtmltoimage --width 1440 --height 1000 https://example.com desktop.png

--width sets the viewport width and --height sets the viewport height. A full-page result can still depend on the build and page layout; test pages with responsive breakpoints, sticky headers and lazy-loaded content.

Format and quality

wkhtmltoimage --format png https://example.com page.png
wkhtmltoimage --format jpg --quality 85 https://example.com page.jpg

Use PNG for sharp text and transparency-sensitive graphics; JPEG is usually smaller for photographic pages. The supported formats and quality behavior are build-dependent, so verify the generated file with file.

JavaScript timing

wkhtmltoimage --javascript-delay 2000 https://example.com rendered.png

The delay gives client-side code time to populate the page after initial load. If the page must not execute scripts, use:

wkhtmltoimage --disable-javascript https://example.com static.png

Disabling JavaScript can remove menus, charts or application content. Increasing delay increases per-request latency; prefer the shortest value that consistently captures the required state.

Local files and resource permissions

The manual documents both disabling local-file access and explicitly enabling it. Keep access disabled unless the page must load local CSS, images or fonts. When access is necessary, allow only the required directory:

wkhtmltoimage --allow /srv/site/assets /srv/site/index.html /srv/screenshots/index.png

Do not enable broad filesystem access for untrusted input. A local HTML document can reference files that the rendering process is permitted to read.

Load-error handling

wkhtmltoimage --load-error-handling abort https://example.com page.png
wkhtmltoimage --load-media-error-handling ignore https://example.com page.png

Choose behavior that matches your pipeline: aborting prevents silently accepting incomplete pages, while ignoring a failed image may be acceptable for non-critical captures. Exact accepted values can vary, so consult the target binary’s help or man page.

6. Make a repeatable server script

This example tries the native headless path and then the Xvfb path only when requested. It validates that an output file exists and is non-empty:

#!/usr/bin/env bash
set -u
URL="${1:?Usage: $0 URL OUTPUT}"
OUTPUT="${2:?Usage: $0 URL OUTPUT}"
WKHTML="${WKHTMLTOIMAGE:-$(command -v wkhtmltoimage)}"
mkdir -p "$(dirname "$OUTPUT")"

if [ "${USE_XVFB:-0}" = "1" ]; then
  exec xvfb-run -a "$WKHTML" --width 1280 --javascript-delay 1000 "$URL" "$OUTPUT"
else
  exec "$WKHTML" --width 1280 --javascript-delay 1000 "$URL" "$OUTPUT"
fi

Run it as:

chmod +x capture.sh
./capture.sh https://example.com /srv/screenshots/example.png
USE_XVFB=1 ./capture.sh https://example.com /srv/screenshots/example-xvfb.png

For systemd, set an explicit PATH, writable output directory and a timeout around the process. Do not run concurrent jobs without testing display allocation, CPU usage and temporary-directory behavior.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

7. Troubleshoot common failures

“Cannot connect to display” or an immediate display error

Cause: this package expects an X server. Fix: install Xvfb, confirm xvfb-run is present, and run xvfb-run -a wkhtmltoimage .... If it still fails, capture stderr and check that the wrapper can create temporary files.

The command works in a shell but fails from cron or systemd

Cause: a reduced PATH, different working directory, permissions or environment variables. Fix: use absolute executable paths, set PATH explicitly, use absolute input/output paths and run under the same service account.

Blank or incomplete image

Possible causes: JavaScript has not finished, required resources are blocked, the URL redirects to an authentication page, or the page uses features unsupported by the Qt WebKit build. Try a measured --javascript-delay, inspect stderr, and compare with --disable-javascript to isolate script-related behavior. Confirm the output file size and content rather than relying only on exit status.

Images or styles fail from a local HTML file

Cause: local-file access is disabled or the resource lies outside an allowed directory. Fix: keep access restricted and add a narrowly scoped --allow path. Avoid enabling unrestricted access for user-supplied documents.

Segmentation fault

IMGKit’s README notes that some wkhtmltoimage versions can fail with segmentation faults. Run the exact command printed by the wrapper directly, preserve stderr, and test the same URL with a minimal option set. Then check whether a different package or supported upstream build is compatible with your distribution; do not assume every segmentation fault has one cause.

Fonts, TLS or proxy problems

Install the fonts your page requires, verify the server’s certificate store and configure network access for the service account. Test the URL with a command-line HTTP client separately. A successful HTTP request does not guarantee that the renderer’s WebKit engine can display every modern page feature.

8. Security and operational safeguards

The project downloads page 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 warning is about wkhtmltopdf, but the same Qt/WebKit rendering risk is relevant to wkhtmltoimage deployments. Treat URLs and HTML as hostile input.

• Run the renderer as a dedicated unprivileged user.
• Sanitize user HTML and JavaScript before rendering.
• Restrict outbound network access where possible.
• Keep local-file access disabled unless a narrowly scoped directory is required.
• Use process, memory and wall-clock limits and remove temporary files.
• Do not expose a renderer endpoint without authentication and input validation.

The upstream README and downloads page should be your reference for project-level behavior and security notices.

Or skip the browser setup

If maintaining Qt WebKit packages, Xvfb processes and rendering edge cases is not part of your application, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF, and it accepts the consent banner before capture while removing more than 60 known consent platforms, newsletter popups and chat widgets. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are reported in X-Page-Verdict and X-Billed headers and cost nothing.

cURL:

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

See the ScreenshotNeo documentation for authentication, output controls and the complete API. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients. Every plan includes features such as full-page lazy-image capture, CSS-selector element shots, custom JavaScript and CSS, waits, blocking, cookies and headers, device presets, PDFs, signed links, async webhooks, bulk capture of up to 100 URLs per call and a usage API. The free plan includes 1,000 shots each month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to try it.

Decision checklist

• Use the native command when your installed build succeeds without a display.
• Use Xvfb when that specific package requires an X server or native rendering fails with a display error.
• Pin and document the binary, distribution release, architecture and option set.
• Set dimensions, JavaScript delay, format, error handling and local-file permissions intentionally.
• Validate exit status and output content, not just file creation.
• Sandbox and sanitize every untrusted page or HTML document.

Frequently Asked Questions

Does every wkhtmltoimage installation require Xvfb?

No. The upstream project describes the tools as headless, while some distribution builds require an X server. Test the exact binary and use Xvfb only when that build needs it.

How can I see which options my package supports?

Run wkhtmltoimage --help and consult the man page for your distribution release; documented options differ between package versions.

What does xvfb-run -a do?

It starts a temporary virtual X server and chooses an available display number before launching wkhtmltoimage.

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.