Run wkhtmltopdf from a small wrapper, not a one-line crontab entry. Give cron an absolute binary path, a known environment, explicit input and output paths, deterministic page-readiness settings, and captured logs. Then run that wrapper as the same account cron uses and validate both the exit status and the generated PDF.
wkhtmltopdf is designed to run headlessly and does not require X11 or a display service. If a command works in your terminal but fails in cron, investigate the different user, shell, working directory, environment, permissions, libraries, fonts, network timing and diagnostics before adding Xvfb.
Why a command works manually but fails in cron
Cron is a deliberately sparse execution environment. On typical Linux cron implementations, commands run as the owner of the relevant crontab; SHELL defaults to /bin/sh, while HOME and LOGNAME come from that account. Output is normally mailed to the owner or the address in MAILTO, although a daemon may route it to syslog. Verify the exact implementation on your host using the crontab documentation and cron documentation.
Your interactive shell may provide a long PATH, aliases, locale settings, font configuration, credentials and a convenient working directory. Cron provides none of those unless you define them. Relative paths can therefore point somewhere unexpected, and a user who can read a file in a terminal may not be able to read it under the job account.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware match#1 Best Overall
- INNOVATIVE CARTRIDGE-FREE PRINTING — No more dealing with lots of tiny ink cartridges; With this wireless document and photo printer each ink bottle set is equivalent to about 90 individual cartridges²
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; When you choose this combination printer, scanner and copier you can print up to 4,500 pages black/7,500 color³
- COLOR PRINTING — Up to 2 years of ink in the box4 (and with every replacement ink set) for fewer out-of-ink frustrations
- ZERO CARTRIDGE WASTE — By using an Epson EcoTank printer you can help reduce the amount of cartridge waste ending up in landfills
- HOME PRINTER DESIGNED FOR RELIABILITY — The Epson EcoTank ET-2800 All-in-One Supertank Color Printer creates vivid, detailed prints and documents thanks to Micro Piezo Heat-Free Technology; Fire off 10 ISO pages per minute1 to easily finish large jobs
The most common differences
- Executable lookup:
wkhtmltopdfis not found because cron’sPATHdoes not include its directory. - Identity and permissions: the cron owner cannot read templates or assets, create the destination directory, replace an existing PDF, or access a private URL.
- Working directory: relative CSS, images and output paths resolve from cron’s starting directory, not your project directory.
- Runtime and fonts: the binary’s libraries, fontconfig setup or installed fonts differ between accounts or hosts.
- Readiness: a page that finishes after asynchronous JavaScript or network requests may be captured before its content appears.
- Observability: warnings and the real exit status disappear into mail or an unmonitored log.
Build a reliable wrapper
Use a dedicated script owned by the job account. The following example assumes a service account named reports; change every path to match your host.
#!/bin/sh
set -u
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/bin
export PATH
export LANG=C.UTF-8
export LC_ALL=C.UTF-8
# Set FONTCONFIG_PATH only when your installation requires a non-standard location.
# export FONTCONFIG_PATH=/etc/fonts
WKHTMLTOPDF=/usr/local/bin/wkhtmltopdf
INPUT=/srv/reports/input/report.html
OUTPUT=/srv/reports/output/report.pdf
LOG=/var/log/reports/wkhtmltopdf.log
TMP="${OUTPUT}.tmp.$$"
umask 027
cd /srv/reports || exit 20
{
printf '%s start id=' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
id
printf 'pwd='; pwd
printf 'version='; "$WKHTMLTOPDF" --version
printf 'n'
} >>"$LOG" 2>&1
# Replace these switches with the readiness and error policy your page needs.
if "$WKHTMLTOPDF"
--load-error-handling abort
--load-media-error-handling abort
"$INPUT" "$TMP" >>"$LOG" 2>&1; then
if [ -s "$TMP" ]; then
mv -f "$TMP" "$OUTPUT"
printf '%s success output=%sn' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$OUTPUT" >>"$LOG"
exit 0
fi
printf '%s error: output is missing or emptyn' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" >>"$LOG"
rm -f "$TMP"
exit 21
else
status=$?
printf '%s wkhtmltopdf exit=%sn' "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" "$status" >>"$LOG"
rm -f "$TMP"
exit "$status"
fiMake it executable and ensure the account can write the log and destination directories:
sudo chown reports:reports /usr/local/sbin/render-report
sudo chmod 0750 /usr/local/sbin/render-report
sudo -u reports /usr/local/sbin/render-reportThe temporary-file-and-rename pattern prevents a reader from seeing a half-written PDF. If overlapping runs are possible, add a lock such as flock around the wrapper or otherwise serialize executions.
Schedule it with explicit timing and logging
Install the schedule for the account that owns the files:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemssudo -u reports crontab -eSHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/bin
[email protected]
17 * * * * /usr/local/sbin/render-reportThis runs at minute 17 of every hour. Cron’s schedule interpretation can be affected by timezone settings such as CRON_TZ; confirm the behavior of your cron daemon. The wrapper’s explicit log remains useful even when mail delivery is disabled.
Does wkhtmltopdf need Xvfb?
No, not according to the project homepage: wkhtmltopdf tools run entirely “headless” and do not require a display or display service (wkhtmltopdf project homepage). Do not add Xvfb as a reflexive fix. First verify the absolute executable path, account permissions, runtime libraries, fonts, input accessibility and page readiness.
Rank #2
- CARTRIDGE-FREE PRINTING — Print lab-quality photos, graphics and creative projects; Get vibrant colors and sharp text with Epson's high-accuracy printhead and Claria ET Premium 6-color inks
- INK BOTTLES — Save on photos1 and creative projects with affordable in-house printing; All-in-one printer allows you to print 4" x 6" photos for about 4 cents each vs. 40 cents with traditional ink cartridges1
- LESS FREQUENT INK REPLACEMENT — Replacement ink bottles don't have to be changed nearly as often as ink cartridges¹; Printer, scanner and copier lets you print up to 6,200 color pages³
- PRINT FOR LONGER — Up to 2 years of ink in the box² (and with every replacement ink set) for fewer out-of-ink frustrations with this wireless printer
- ZERO CARTRIDGE WASTE — Epson EcoTank printer helps reduce the amount of cartridge waste ending up in landfills; Cartridge-free printer uses high-yield ink bottles; Each replacement ink bottle set is equivalent to about 100 individual ink cartridges⁴
A wrapper or locally packaged build might have unusual requirements. If a specific build demonstrably fails without a display, document that build-specific fact and test the virtual-display setup separately; it is not a general wkhtmltopdf prerequisite.
Pin and inspect the renderer build
The official downloads page lists 0.12.6 as the stable release, dated June 11, 2020 (downloads and build notes). Record the complete output of:
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 →/usr/local/bin/wkhtmltopdf --versionPay attention to whether it says with patched qt. Distribution packages and upstream binaries can differ in available switches and behavior. “Static” Qt does not mean the host needs no other runtime components; the target distribution, architecture, shared libraries, fontconfig and fonts remain part of the deployment specification.
The project status page notes that Qt 4 has not been supported since 2015 and its WebKit has not been updated since 2012. The upstream GitHub repository was archived on January 2, 2023. Treat wkhtmltopdf as a maintenance-sensitive legacy renderer: pin the exact package, test upgrades in a staging job and retain the version in your diagnostics (project status, changelog/archive information).
Make input, assets and fonts deterministic
Local files
- Use absolute file paths or an explicit working directory.
- Confirm the cron account can read the HTML, CSS, images and fonts.
- Use the local-file access controls supported by your installed build; do not assume a package enables every option.
- Keep generated files outside directories that are writable by untrusted users.
Check access as the real account, not as root:
sudo -u reports test -r /srv/reports/input/report.html
sudo -u reports test -w /srv/reports/output
sudo -u reports /usr/local/bin/wkhtmltopdf --versionNetwork resources
A URL may resolve manually but fail from a restricted service account, container or firewall policy. Test DNS, TLS and authentication as that account. Supply required headers, cookies or credentials through a controlled mechanism, and never place secrets in world-readable command lines or HTML.
Fonts and layout
Different installed fonts or fontconfig/freetype configuration can change glyph substitution, line breaks and pagination. Install the fonts your document actually requires, refresh fontconfig caches where your distribution needs it, and compare rendered output after package changes. A missing font is often reported only as a visual difference, not a process failure.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
- SET IT UP ONCE AND PRINT WITH CONFIDENCE. No complicated maintenance. Just easy, reliable printing you can count on.
- INK FOR YEARS. NOT MONTHS. Up to 2 years of ink included. Get thousands of pages of cartridge-free printing. More pages, less hassle
- KEEPS PRINTING WELL AFTER COMPETITORS HAVE QUIT. No complex maintenance. Sharper text, richer colors.[2] Only with HP Smart Tank
- PREMIUM SUPPORT - Strong technical expertise to solve issues faster
- THE LAST PRINTER YOU'LL EVER NEED. Enjoy years of refillable, cartridge-free printing.
Control JavaScript readiness and load errors
The usage manual documents JavaScript enabled by default, a 200 ms delay, configurable delay, --window-status, and page-load error policies such as abort, ignore and skip (usage manual). These are mechanisms, not a universal recipe.
Static HTML
If JavaScript is unnecessary, disable it and keep the source self-contained. This reduces timing variability.
Asynchronous applications
A fixed delay is only a guess. Prefer a page-controlled readiness signal when the application can set window.status after data and images are ready:
wkhtmltopdf --window-status report-ready https://internal.example/report /srv/reports/output/report.pdfOtherwise choose a delay based on measured worst-case latency, test under load, and set an explicit load-error policy. Aborting on failed media is safer for reports where an incomplete page must never be published; ignoring an optional tracker may be acceptable for a different document. Confirm that the options exist in your installed build, because some features require patched Qt.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Capture errors and distinguish success from a good document
Always capture both streams and preserve the converter’s exit code. In addition to cron mail, send the wrapper log to your normal system logging or monitoring pipeline. Search for warnings about blocked resources, network errors, JavaScript exceptions, missing files and unsupported CSS.
A zero exit status proves only that the process completed according to its policy. Check that the output exists, is non-empty and is structurally usable. For important reports, inspect page count or extract text and compare a known-good rendering. Alert on unexpected size changes or missing sections rather than trusting process completion alone.
Rank #4
- Wireless Bluetooth Printer: Portable thermal printer compatible with iPhone, Android phones, iPad and tablet computers via Bluetooth. For smartphones, please download the "Nada Print" App. You can also connect to laptops and computers for printing using a USB-C cable. (Note: Laptops and computers can only be connected via USB and require the installation of a driver first. Bluetooth connection is not supported.)
- No-ink printing: Only supports US Letter and A4 size thermal paper.(Doesn't support regular paper) The no-ink portable thermal printer uses direct thermal technology, requiring no ink, toner or ribbons, making it environmentally friendly, cost-effective and time-saving. The thermal printer package comes with a roll of US Letter thermal printing paper. Note: When installing the paper, remember to switch the paper size switch on APP
- Clear Print: NDYIN N80 portable thermal printer adopts high-definition printing technology, with a 203DPI resolution to provide you with clear printing results. This mobile printer is compatible with roll paper, folded paper and tattoo transfer paper, supporting printing from your mobile phone PDF, Word, pictures and web pages anytime and anywhere. It is recommended to use our NDYIN thermal paper to achieve good printing quality
- Portable wireless printer for travel: The thermal printer is equipped with a built-in 1500mAh rechargeable battery, which can print 160 sheets of 8.5" x 11" thermal paper after being fully charged. It weighs only 1.5 pounds and is compact in size. This ink-free portable printer can be easily carried in a backpack or briefcase! It is perfect for business travel, cars, small offices, construction sites, schools and homes. You can print documents, contracts, invoices and boarding passes anytime and anywhere
- The N80 thermal printer has a wide range of uses. The package includes the N80 printer, a roll of US Letter paper(7m/roll), a user manual, a guide card, a type-C soft cable and a type C adapter. Note: The charging adapter is not included. Special thermal paper is required for use; ordinary paper cannot be used. This ink-free portable thermal printer is suitable for various scenarios such as home, school, travel, office, and outdoor, meeting the printing needs of different groups of people. This tattoo template printer is also compatible with tattoo transfer paper, making it an ideal choice for tattoo art
Security boundaries for scheduled rendering
The wkhtmltopdf 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 you are running it on!” (project security guidance). Treat templates, URLs, JavaScript and downloaded resources as potentially hostile.
- Run the job as a restricted service account with no unnecessary shell, SSH or write access.
- Expose only the input and output directories it needs.
- Use operating-system confinement. The project documents AppArmor restrictions and identifies SELinux as the corresponding approach on Red Hat/Fedora systems (AppArmor guidance).
- Restrict outbound network access where reports do not need the internet.
- Sanitize user HTML and JavaScript; do not render arbitrary URLs with production credentials or filesystem access.
- Keep logs free of tokens, cookies and authorization headers.
Why fonts or images are missing in cron-generated PDFs
- Check the URL or path in the log. Replace relative references with absolute paths or URLs.
- Test as the cron user. Use
sudo -u reportsfor file, DNS and HTTPS checks. - Inspect font installation. Confirm the intended family is installed and fontconfig sees it; compare
wkhtmltopdf --versionbetween environments. - Allow enough readiness time. Late API responses and lazy-loaded images need a real ready condition or a tested delay.
- Review local-file and network policies. A security option or sandbox may intentionally block the resource.
- Fail loudly when required media is absent. Use an abort policy for mandatory assets and validate the resulting PDF.
When another renderer is a better operational choice
The wkhtmltopdf project suggests considering WeasyPrint or commercial Prince for controlled, mostly static report generation, and Puppeteer or a wrapper for sites that depend on modern JavaScript (project recommendations). Choose by these axes:
| Question | wkhtmltopdf | Alternative decision point |
|---|---|---|
| Existing HTML/CSS fidelity | Often preserves an established WebKit-oriented template. | Test pagination, fonts and CSS before migrating. |
| JavaScript readiness | Basic controls such as delay and window status. | Puppeteer is designed for browser-driven dynamic pages. |
| Maintenance and security | Legacy Qt/WebKit stack; pin and isolate it. | Evaluate the project’s maintenance posture and patch process. |
| Deployment footprint | Requires a compatible build, runtime libraries and fonts. | Compare OS packages, container size and font management. |
| License and cost | Check the package and license you deploy. | Prince is commercial; compare licensing with operational needs. |
| Observability | Requires your own wrapper, logs and validation. | Choose tooling that exposes failures your team can monitor. |
Or skip the browser setup
If your goal is a clean screenshot or PDF rather than maintaining a scheduled wkhtmltopdf host, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP or PDF. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers report the page verdict and billing status.
It also provides full-page and element capture, lazy-image loading, dark mode, device presets and custom viewports, retina scale, PDF paper and margin controls, custom CSS and JavaScript, clicks, selector hiding, selector/delay/network-idle waits, request and resource blocking, custom headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable caching, signed image links, asynchronous jobs with signed webhooks, bulk capture for up to 100 URLs per call, a usage API and an OpenAPI specification. An MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.
For API details, see the ScreenshotNeo documentation. cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
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}`);The Free plan includes 1,000 shots each month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Operational checklist
- Pin and record the exact
wkhtmltopdf --version, including patched-Qt status. - Run a wrapper as the same account and with a near-minimal environment.
- Use absolute paths, explicit locale and any required fontconfig variables.
- Verify input, asset and output permissions.
- Choose JavaScript readiness and load-error policies deliberately.
- Capture stdout, stderr, exit status and diagnostic identity information.
- Validate output existence, size and content, not just process completion.
- Prevent overlapping writes with locking or atomic replacement.
- Constrain the account, filesystem and network when rendering untrusted or user-influenced content.
Frequently Asked Questions
What account does cron use for a wkhtmltopdf job?
The owner of the crontab in which the entry is installed. Test the wrapper with that same account.
Is a 200 ms delay enough for a JavaScript application?
Not necessarily. It is the documented default, not proof that asynchronous data and images are ready; use a real readiness signal or a tested delay.
What should I record when moving the job to another server?
Record the operating system and architecture, package source, complete wkhtmltopdf version, patched-Qt status, runtime libraries, font packages, locale and wrapper configuration.
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.
