If pdfkit fails with wkhtmltopdf exited with non-zero code and Could not connect to any X display, the failure is usually in wkhtmltopdf’s Qt/X display startup—not in pdfkit’s Python call itself. On a headless Linux server, a common fix is to run wkhtmltopdf under a virtual display using xvfb-run -a, then configure pdfkit to invoke that wrapper. First verify the exact binary and environment used by the failing service; a command that works in your terminal may not be the one your web worker runs.
What the error means
pdfkit is a Python interface that invokes the separate wkhtmltopdf executable to render a document. The message qt.qpa.screen: QXcbConnection: Could not connect to display followed by Could not connect to any X display indicates that the renderer could not connect to a logical display while initializing its Qt/X11 layer. Qt identifies missing logical displays as a typical issue in headless execution and describes virtual displays such as Xvfb as one Unix approach.
A headless server, container, background worker, or web-service process often has no graphical session. The message alone does not prove which condition caused the failure: the display may be absent, unset, inaccessible to the service account, or affected by the particular wkhtmltopdf build and its environment. Treat it as a display-connection failure to diagnose, rather than proof that a specific package is broken.
Start by checking the failing service’s environment
Before changing packages, confirm what the process that fails actually runs. A shell test is useful only if it uses the same executable and substantially the same user, container image, paths, and environment as the application.
Recommended Free Tools
#1 Best Overall
- Edit PDFs with Ease. Modify text, images, and layouts directly within your PDF documents.
- Convert & Organize. Export PDFs to Word, Excel, or ePub, and organize files with ease.
- Read & Annotate. Enjoy intuitive reading modes and powerful tools to comment, highlight, and mark up PDFs.
- Create & Manage PDFs. Create new PDFs, combine multiple files, scan documents, and compress for easy sharing.
- Fill & Sign Forms. Complete forms and digitally sign documents with secure e-signature tools.
- Identify the service context. Note whether the error comes from Django/uWSGI, a job worker, a container, or another process. Record the service account and the OS or container base image.
- Check the renderer version and executable path as that account. Run
wkhtmltopdf --versionin the same image and service context if possible. Confirm which binary the process finds on itsPATH; the interactive shell may resolve a different copy. - Capture the full failure. Preserve stderr, the exact command or arguments, and the executable path. Also note relevant display-environment settings and whether a display is intentionally available.
- Compare terminal and service behavior. If a terminal invocation succeeds but the application fails, investigate differences in user, environment, executable, and library availability before concluding that the renderer itself is at fault.
A Django/uWSGI report illustrates this terminal-versus-service discrepancy, but it is an example rather than evidence that one particular deployment fix applies universally.
Fix a headless Linux host with Xvfb
If the process is headless and the installed wkhtmltopdf needs a display, provide a virtual X display for the render. The pdfkit project wiki documents wrapping wkhtmltopdf with Xvfb, including an xvfb-run pattern.
- Install the distribution’s Xvfb package. Use the package name and package manager for the OS image you deploy. Confirm that both Xvfb and
xvfb-runare installed in the same host or container where the service runs. - Test the renderer under the wrapper. From the failing environment, try
xvfb-run -a wkhtmltopdf input.html output.pdf. Replace the input and output paths with files accessible to the service account. The-aoption asks the wrapper to select an available display number. - Configure pdfkit to use the wrapper. pdfkit provides a configuration mechanism for selecting the wkhtmltopdf executable. Point it at an executable wrapper that runs
xvfb-run -a wkhtmltopdf, or use the wrapper arrangement documented by the pdfkit wiki. Ensure the wrapper forwards pdfkit’s arguments correctly. - Check permissions and paths. The wrapper must be executable by the service account; its interpreter,
xvfb-run, and wkhtmltopdf must resolve correctly in that service’s environment. Verify quoting and paths if input names or arguments can contain spaces. - Retest through the application. Generate a small PDF through the same route, worker, or job that failed. A successful manual command is not a substitute for testing through the real service.
The wiki’s examples are community-maintained and include distribution-specific details. Validate package names, binary locations, and wrapper behavior against your actual distribution and installed pdfkit version rather than copying a path blindly.
Rank #2
- EVERY PDF TOOL UNLOCKED - 30+ tools in one app: edit text and images, convert, merge, split, compress, sign, OCR, redact, watermark, batch process, and more. No feature gates, no upsells, nothing held back.
- PAY ONCE, OWN FOREVER — A one-time purchase, not a subscription. Other apps runs $240/year — Scrivar is yours for life, with free updates included.
- UNLIMITED eSIGN, BUILT IN — Send contracts and forms for signature and track every step. Recipients sign in their browser with no account or app needed. Replace DocuSign and save hundreds a year.
- PC, MAC, AND WEB — Install on any Win 10/11 PC or macOS 11+ Mac (Intel or Apple Silicon), or work in your browser at scrivar.com. Same tools, same account, everywhere you work.
- OCR + FULL OFFICE CONVERSION — Turn scanned documents into searchable, selectable text, and convert PDFs to and from Word, Excel, and PowerPoint with formatting kept intact.
Choose the remedy that matches the situation
| Remedy | Best fit | What to verify |
|---|---|---|
xvfb-run wrapper |
A headless Linux process whose installed renderer needs an X display | Xvfb and the wrapper are present, executable, and visible to the service process. |
| Different wkhtmltopdf package or build | Evidence points to the selected binary, its packaging, or its dependencies | Match the OS version, architecture, dependencies, and features your application needs. |
| Existing real display | The application is intentionally running within a graphical session | Confirm the service can access that display; an interactive user’s display is not automatically available to a service. |
Do not switch builds solely because a community post says another package worked for someone else. The wkhtmltopdf packaging releases page lists OS- and architecture-specific artifacts, and the repository page records that it was archived on 2023-08-28. Check compatibility and dependencies before selecting an artifact; community reports are clues, not guarantees.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Why not just enable SSH X11 forwarding?
SSH X11 forwarding can expose a graphical display in some interactive workflows, but it is not the usual solution for automated headless PDF generation. First establish whether the application is supposed to use an actual graphical session. If not, the documented pdfkit approach is to run the renderer under a virtual display. If there is an intentional display, confirm that the service—not merely your login shell—can access it.
Common failure patterns and what to check
The wrapper works in a shell, but pdfkit still reports the display error
- Confirm that pdfkit is configured to invoke the wrapper rather than the original wkhtmltopdf binary.
- Check that the configured executable path is correct inside the service’s container or host.
- Make sure the wrapper passes the complete argument list through and runs as the service account.
- Inspect the application’s captured stderr to see whether the failing invocation is actually wrapped.
The command works manually but fails in Django, uWSGI, or a worker
Compare the user, PATH, executable path, environment, and installed libraries. A deployment’s interactive shell and service can resolve different binaries or run with different permissions. Test the render through the failing route or worker after correcting the discrepancy.
Rank #3
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- 1 Year License for 1 Windows & 2 Mobile (Android and/or iOS) devices.
Xvfb is installed, but xvfb-run cannot be found
Installation of a virtual-display package does not establish that the wrapper executable is on the service’s PATH. Locate it in the deployed image, configure a valid executable path, and check access permissions for the service account.
The error persists after adding Xvfb
Recheck that the failing process really uses the wrapper and that the wrapper can start both Xvfb and the intended wkhtmltopdf binary. If it does, capture the exact executable, version, OS or image, service user, arguments, and stderr. Then investigate whether the selected build and its dependencies suit that platform; the display message by itself does not identify a build defect.
A package change seems to fix one machine but not another
Do not generalize from that result. Different OS releases, architectures, libraries, and application requirements can make package behavior differ. Compare those details and test the chosen artifact in the actual deployment image before rolling it out.
Rank #4
- PDF editor for all cases - fully edit, merge, create, compare, reduce PDFs, edit page structure
- incl. NEW OCR module: for text and image recognition in scanned documents
- Merge several PDF documents into one document
- Edit text and images directly in the document
- NEW in version 2: 4K and 8K resolution
Retest and make the fix durable
After changing the wrapper or build, test both a direct render and the application’s real generation path. Use a small representative input and confirm that the resulting PDF can be opened and contains the expected page content. Keep the executable selection and wrapper setup in deployment configuration so new containers or hosts do not silently revert to an unwrapped binary.
- Record the wkhtmltopdf version and resolved path used by the service.
- Keep the wrapper, Xvfb package, and required executable paths in the same image or host configuration as the application.
- Capture stderr and the service context when errors recur; the top-level pdfkit exception may only report that its child process exited unsuccessfully.
Or skip the browser setup
If your actual goal is to capture a webpage rather than preserve an existing wkhtmltopdf-based HTML-to-PDF pipeline, ScreenshotNeo offers a hosted screenshot API and MCP server. One GET request can return a clean screenshot; the service also supports PDF output. The call below is the one-call screenshot example—see the ScreenshotNeo documentation for API options, including output selection.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response reports the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. These are recurring plan allowances and prices as presented for the service; yearly billing gives two months free. All listed features are available on every plan.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Sign up for ScreenshotNeo’s free plan to try 1,000 screenshots a month with no card.
Best Value
![Corel PDF Fusion - PDF Creator Toolkit [PC Disc]](https://m.media-amazon.com/images/I/51YTjW7jL6L._SL160_.jpg)
- Assemble, edit, and create PDFs with this easy to use, all in one PDF creator
- Open and view over 100 file types, without purchasing additional software
- Drag and drop multiple different file types into one PDF document
- Easily add new text and comments to PDFs
- Share your created documents with anyone in PDF, PDF/A, XPS or Microsoft Word formats
Frequently Asked Questions
Does this error mean pdfkit itself is broken?
Not necessarily. The message points to wkhtmltopdf’s Qt/X display initialization, which pdfkit invokes as a separate executable.
Will Xvfb fix every wkhtmltopdf installation?
No. It addresses a missing virtual display in suitable headless Unix setups; executable selection, permissions, build compatibility, and service configuration still matter.
Can I keep using pdfkit after adding an Xvfb wrapper?
Yes, provided pdfkit is configured to invoke the wrapper and the service account can execute it and its dependencies.
Quick 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.
