Short answer: wkhtmltopdf chooses its destination from the final positional argument. Give it a filename to create a file, or give it - to write the PDF to standard output. xvfb-run only supplies a virtual X display; it does not redirect PDF output. For example, xvfb-run -a wkhtmltopdf https://example.com - > report.pdf is the stdout form, while xvfb-run -a wkhtmltopdf https://example.com report.pdf writes directly to a named file.
A historical issue report describes stdout failing for one Ubuntu user while a named file worked. That is useful diagnostic evidence, not proof that stdout is universally incompatible with xvfb-run. The executable, Ubuntu package build, shell redirection, and wrapper setup all matter.
How wkhtmltopdf decides where the PDF goes
The command-line shape is wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>. The final argument is the output destination.
| Command | Destination | Use it when |
|---|---|---|
wkhtmltopdf https://example.com report.pdf |
A named file | The result must persist on disk or be passed to another program by path. |
wkhtmltopdf https://example.com - > report.pdf |
Standard output, redirected by the shell | A pipeline or calling process controls where the bytes are stored. |
wkhtmltopdf https://example.com - | downstream-command |
Standard output, piped | The next process accepts a PDF stream. |
In the library API, an output path of - also means stdout. An empty library output setting means an in-memory buffer; that is different from the command-line convention and should not be substituted for the CLI’s final argument.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
What xvfb-run changes—and what it does not
Ubuntu’s xvfb-run wrapper creates an X authority file, starts Xvfb, assigns the wrapped command a display and authority, then cleans up. With -a, it searches for a free display number beginning at 99. Its documented default virtual screen is 1280×1024 with 24-bit color, and the wrapper requires xauth.
That display environment is independent of output routing. These are separate, valid patterns:
wkhtmltopdf https://example.com report.pdf
wkhtmltopdf https://example.com - > report.pdf
xvfb-run -a wkhtmltopdf https://example.com report.pdf
xvfb-run -a wkhtmltopdf https://example.com - > report.pdfThe shell performs > report.pdf. wkhtmltopdf writes PDF bytes to stdout, while its diagnostics remain on stderr. Keeping those streams separate is essential: text accidentally sent into the PDF stream can make the file unreadable.
Choose a file or stdout for the downstream job
Named output
A filename is the least surprising choice for a scheduled conversion, an audit trail, or a workflow in which another command opens a path later. Check the directory, ownership, free space, and permissions before blaming wkhtmltopdf. Use an absolute path in services whose working directory may differ from your interactive shell.
stdout output
Use - when a web service, queue worker, or pipeline should consume the PDF without a temporary file. Redirect or pipe it explicitly and capture diagnostics separately:
set -o pipefail
xvfb-run -a wkhtmltopdf https://example.com - 1>report.pdf 2>wkhtmltopdf.log
status=$?
printf 'exit status: %sn' "$status" >&2
exit "$status"There is no documented performance advantage in the supplied material for either destination. The practical difference is persistence and stream handling, not the virtual display.
A disciplined Ubuntu diagnosis
- Identify the executable. Run
command -v wkhtmltopdfandwkhtmltopdf --version. Compare that binary with the package manager’s installed package information. Different builds can have different behavior and options. - Reproduce with identical inputs. First run
wkhtmltopdf URL named.pdf, thenwkhtmltopdf URL - > stdout.pdf. Keep URL, global options, environment, and user account the same. Capture stderr and record each exit status. - Add the wrapper deliberately. Repeat both tests with
xvfb-run -aonly when the installed build or runtime needs a display. The project describes wkhtmltopdf as headless, but that does not guarantee identical behavior for every distribution build, option, or plugin. - Check wrapper prerequisites. If failure occurs before conversion, verify that
xauthis installed and that Xvfb can start. Look for authority-file, display-allocation, or X-server messages on stderr. - Inspect the output argument. Confirm that
-is the final output argument, not an input URL or an option value, and that no later shell token changes the command. Quote URLs containing shell metacharacters. - Separate data from logs. Never merge stderr into stdout for a PDF stream. Avoid constructs such as
2>&1when stdout is being saved as the PDF. - Check the produced bytes. Confirm the file is non-empty and begins with a PDF signature such as
%PDF-. A shell error, an HTML error page, or a diagnostic line indicates a pipeline or conversion failure rather than a valid PDF. - Compare outside and inside xvfb-run. If the build works without the wrapper, determine whether the wrapper is actually required. If it fails only with the wrapper, focus on
xauth, display selection, environment variables, and wrapper errors rather than output semantics.
Ubuntu versions and build differences
Do not generalize one Ubuntu package to all Ubuntu installations. The Bionic manpage described wkhtmltopdf 0.12.4-1 and explicitly noted that its package did not use wkhtmltopdf’s patched Qt. Focal documentation covered 0.12.5-1ubuntu0.1, while Jammy package metadata lists xvfb as a virtual-framebuffer option. Those statements describe named releases and package contexts, not every Ubuntu release or third-party binary.
The project’s homepage describes wkhtmltopdf as running headlessly. A distribution package can still differ in patches, dependencies, defaults, and supported options. Always record the exact version and package source in bug reports and deployment notes.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Common symptoms, causes and fixes
| Symptom | Likely area | What to check |
|---|---|---|
| Named file works; stdout exits 1 | Build-specific behavior, argument order, redirection, or mixed streams | Run the same command with -, capture stderr separately, verify the binary and final argument, and compare versions. |
Both forms fail only under xvfb-run |
Wrapper setup | Install/verify xauth, inspect Xvfb startup messages, try -a, and check display environment variables. |
| Output PDF is corrupt | Diagnostic text entered the binary stream | Use 1>file 2>log; do not combine stderr with stdout. |
| No output file appears | Shell path or permissions | Use an absolute writable path, inspect the shell exit status, and check disk space. |
| Conversion hangs or times out | Page load or runtime behavior | Read stderr, test a minimal URL, and distinguish a page/conversion problem from stdout routing. |
| The command is “not found” | Installation or PATH | Use command -v, inspect the package installation, and invoke the intended absolute binary. |
The old “Can’t write on STDOUT” report should be treated as a reproduction lead. It records one user’s observation that xvfb-run wkhtmltopdf ... - failed while a file destination worked; it does not establish a universal root cause.
Automation and security boundaries
For a service, log the command version, URL (subject to your privacy policy), exit status, stderr, and destination mode. Use unique temporary paths when files are unavoidable, and clean them after successful hand-off. For stdout pipelines, propagate non-zero statuses; otherwise a failed conversion can look like a successful downstream job.
Sanitize untrusted HTML and JavaScript before giving it to wkhtmltopdf. The project warns against running the tool on unsanitized user-supplied content. xvfb-run supplies a virtual display; it is not an HTML sanitizer or an isolation boundary.
Or skip the browser setup
If your real requirement is a clean screenshot or PDF of a URL rather than a local wkhtmltopdf process, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets before capture; bot checks, blank pages, timeouts, failed loads and cache hits are not billed. Its response identifies the page verdict and billing status with X-Page-Verdict and X-Billed headers. An MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.
One-call cURL example (see the ScreenshotNeo documentation for all options):
Best Value
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpEquivalent 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)Equivalent 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}`);Every plan includes the features: full-page and element capture, device presets or custom viewports, retina scale, PDF controls, HTML/CSS rendering, custom JavaScript and CSS, waits, request blocking, headers and cookies, timezone and geolocation, transparency, resizing, caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting and an OpenAPI specification. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Frequently Asked Questions
Does a trailing slash or URL scheme determine stdout behavior?
No. The output destination is determined by the final positional argument; the URL is an input. Use a fully qualified URL and place - last.
Can I redirect stderr to a separate file while streaming stdout?
Yes. Use separate descriptors such as 1>output.pdf 2>conversion.log and propagate the command’s exit status.
Recommended Free Tools
Is xvfb-run mandatory on every Ubuntu installation?
No universal rule is established. The installed wkhtmltopdf build and the page/options you use determine whether a virtual display is needed.
The Bottom Line
Use a filename when you need a durable path; use the final argument - when another process should consume PDF bytes. Treat xvfb-run as display setup, not output routing, and diagnose the exact Ubuntu build, wrapper prerequisites, shell streams and exit status before declaring stdout unsupported.
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.
