wkhtmltopdf Error: Cannot Connect to X Server on Linux
This error usually points to an unpatched Qt build. Check your installed binary, then choose a compatible patched build, Xvfb workaround, or another renderer.
If wkhtmltopdf says it cannot connect to the X server on Linux, first check which build you installed. The error often occurs with a build compiled without the patched Qt support that allows headless operation. A compatible patched-Qt package is usually the simplest headless fix; running an unpatched build under Xvfb may work as a workaround. Linux packages differ, so there is no safe universal install command.
1. Diagnose the installed build
Run these commands in the same shell, container, or service environment where the PDF job fails:
wkhtmltopdf --version
command -v wkhtmltopdf
uname -m
cat /etc/os-releaseRecord the version output, including whether it says with patched qt, the executable path, CPU architecture, distribution and release, and how the package was installed. The command name alone does not identify the build. If a service runs the command, inspect its environment too: the executable found from an interactive shell may not be the one used by the service.
The upstream project describes headless operation, but that does not apply to every distribution package. For example, Ubuntu Jammy’s manual says its unpatched-Qt build cannot run without X11. This describes that package; it should not be generalized to every Ubuntu, Debian, container, or third-party build. Project overview · Ubuntu Jammy manual
2. Choose a fix that matches your environment
Option A: Install a compatible patched-Qt build
If the job must run without a display service, use a wkhtmltopdf package compatible with your distribution release and architecture that includes patched Qt. Check the project’s distribution-specific downloads and the package dependencies before replacing the binary. Do not copy a package or installation command meant for another Linux release or architecture.
After installation, verify the executable path and version again, then render a representative input and confirm that the PDF features your application uses still work. The upstream manual identifies --use-xserver for using an X server; build configuration is a central diagnostic distinction. Official downloads · Usage manual
Option B: Try Xvfb with the existing unpatched build
If changing the package is impractical, run the job under a virtual X server. For example, in environments where the xvfb-run wrapper is installed:
xvfb-run -a wkhtmltopdf input.html output.pdfThis creates a virtual display for the process; it does not mean the machine needs a physical monitor. Test this in the same container, service account, and runtime environment used in production. Compare the generated output with your expected output, especially if you rely on headers, footers, outlines, or other features that can vary between patched and unpatched builds.
Option C: Reconsider the renderer
For a new system or a workflow that needs modern browser behavior, compare a replacement renderer before investing in workarounds. The wkhtmltopdf project points to WeasyPrint or Prince for controlled report generation and Puppeteer for JavaScript-heavy sites. Check current maintenance, supported HTML/CSS and JavaScript behavior, operating-system dependencies, and the PDF features your application needs before migrating. Project status and alternatives
3. Minimal PDF smoke test
Once the build or virtual display is set up, test a local HTML file first. This separates an X-server problem from network access, remote assets, and application-specific HTML.
cat > /tmp/wkhtmltopdf-smoke.html <<'HTML'
<!doctype html>
<html><head><meta charset="utf-8"><title>PDF smoke test</title></head>
<body><h1>PDF smoke test</h1><p>If this text appears, basic rendering completed.</p></body></html>
HTML
wkhtmltopdf /tmp/wkhtmltopdf-smoke.html /tmp/wkhtmltopdf-smoke.pdf
file /tmp/wkhtmltopdf-smoke.pdfIf using Xvfb, prefix the conversion command with xvfb-run -a. If the smoke test succeeds but the application conversion fails, inspect the input document, external resources, process environment, and PDF options separately.
4. Common errors and fixes
| Symptom | Likely cause | What to check |
|---|---|---|
| Cannot connect to X server | The build expects X11, or the environment has no usable display. | Check wkhtmltopdf --version and package origin. Use a compatible patched-Qt build, or try xvfb-run with the unpatched build. |
| It works in a terminal but fails in a service or container | The service may use a different executable, user, environment, or package set. | Log command -v wkhtmltopdf, version, architecture, and relevant environment in the actual runtime context. Test the same command as the service account. |
| The replacement package will not install or start | Package release, architecture, or required system libraries may not match. | Check OS release and architecture against the package instructions and dependencies. Avoid treating a static build as dependency-free; upstream notes that static builds still need system packages. |
| The PDF is produced but headers, footers, outlines, or layout differ | Build variants have different capabilities, or the renderer interprets the source differently. | Verify the patched-Qt status and test every required output feature against a known sample before rollout. |
| Local HTML works but a web page fails or is incomplete | Remote assets, JavaScript timing, network access, or input-specific behavior may be involved. | Check access to fonts, stylesheets, images, and scripts from the rendering environment. If modern JavaScript behavior is essential, assess a current browser-based renderer. |
5. Reliability, performance, cost, and security
- Reliability: Pin the package source and version in your deployment, record the binary path and build label, and run a representative PDF smoke test after OS or package changes. Validate the exact features your output depends on.
- Performance: This error is a display/build configuration problem, not a signal that a larger server will fix the issue. First make the renderer run reliably in its actual environment. For slow jobs, separately inspect remote resource loading, document complexity, and JavaScript behavior; choose a renderer that fits those requirements.
- Cost: Compare the ongoing effort of maintaining the package and its OS dependencies with the cost and compatibility of migration. No performance or cost benchmark can be inferred from the error alone.
- Security: Treat HTML and JavaScript passed to wkhtmltopdf as sensitive input. The project warns that untrusted HTML/JS can compromise the server. Sanitize user-supplied content and consider process confinement such as AppArmor or SELinux.
Or skip the browser setup
If your task is taking a screenshot of a web page rather than generating a PDF from your own HTML, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF. Its clean-shot steps can accept cookie and consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off.
See the ScreenshotNeo API documentation. Example request:
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpBot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers identify the page verdict and billing status. An MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.
Sign up free for 1,000 screenshots a month, no card required.
FAQ
Does this error mean Linux needs a physical monitor?
No. It usually means the installed build expects an X server that is unavailable in that runtime. A compatible headless build or a virtual X server can address that configuration.
Does --use-xserver fix the problem?
It selects use of an X server; it does not create one. Use it only when a usable X server is available, or provide a virtual display such as Xvfb where appropriate.
Is every package labeled wkhtmltopdf headless?
No. Check the build label and package documentation for the exact binary you run. Distribution and third-party packages can differ.
Should I migrate away from wkhtmltopdf?
Consider migration when you need modern JavaScript or CSS behavior, or when maintaining the older Qt/WebKit stack no longer fits your requirements. Verify the replacement against your real documents and deployment environment.
