Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
“wkhtmltopdf: command not found” means the process that ran the command cannot resolve an executable named wkhtmltopdf. Either wkhtmltopdf is not installed in that environment, or its directory is not on that process’s PATH. Check command lookup as the same user and inside the same service, job, shell, or container that failed. Then install it there or configure your application with the executable’s full path.
What the error actually tells you
This message appears before HTML is rendered and before PDF generation starts. The shell (or a program launching the command) searched its configured executable paths and found no callable file named wkhtmltopdf. A successful test in your desktop terminal does not prove that a web service, scheduled job, worker, or container can see the same binary.
wkhtmltopdf is a headless, open-source (LGPLv3) command-line utility that renders HTML to PDF; the related wkhtmltoimage tool renders image formats with Qt WebKit. The immediate fix is therefore about installation and command discovery, not about CSS, page content, or PDF options.
Fastest reliable fix
- Enter the failing execution context. Use the same account and environment as the application that reports the error. For a service, run a diagnostic through that service or its shell; for Docker, open a shell in the running container.
- Check resolution. Run the following commands:
command -v wkhtmltopdf
which wkhtmltopdf
wkhtmltopdf --versioncommand -v is generally preferable on POSIX shells because it is a shell builtin. If both lookup commands return nothing, the executable is absent from that environment or its directory is not in PATH. If a path is returned but --version fails, you have moved beyond the original lookup problem and should inspect permissions and runtime dependencies.
#1 Best Overall
- Install wkhtmltopdf in that same environment if no path is found.
- Set an explicit path in the calling application if the binary exists outside the process’s
PATH. - Run the version check again as the application user, then perform a small PDF conversion.
Install it for the operating system that runs your job
The commands below are examples documented by a current community integration. Package names, repositories, supported architectures, and available builds vary by distribution and release, so confirm that your operating system accepts the package before using a command in production.
Ubuntu or Debian
sudo apt-get update
sudo apt-get install wkhtmltopdf
wkhtmltopdf --versionRun the final version command in the same user context as the failing process. A package installed for the host does not help a process running in a separate container or virtual machine.
CentOS, RHEL, or Fedora
sudo yum install wkhtmltopdf
# or, on systems using DNF
sudo dnf install wkhtmltopdf
wkhtmltopdf --versionUse the package manager and repositories appropriate to your exact release. If no package is available, use a compatible upstream build only after checking CPU architecture and required system libraries.
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 reinstallCrashes, 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 minutemacOS
brew install wkhtmltopdf
wkhtmltopdf --versionHomebrew’s installation prefix differs between Intel and Apple-silicon Macs. If the command works interactively but not from a launch daemon, configure that daemon with the absolute path rather than assuming it inherits your shell profile.
Windows
Install a build from the project’s downloads page, choosing the installer that matches your Windows edition and CPU architecture. Then open a new terminal and run:
wkhtmltopdf.exe --versionTypical integration defaults include C:Program Fileswkhtmltopdfbinwkhtmltopdf.exe. Treat that as an example, not a guaranteed location; verify the file on the machine where the application runs.
When it works in your terminal but fails in the application
This is a process-environment mismatch. Interactive shells often load profile files that add directories to PATH; services, web servers, queue workers, cron jobs, and systemd units may use a minimal path. Different users may also have different permissions and home directories.
Free tools Windows power users keep installed
One-click scans. No signup required.
Prove which environment is failing
- Identify the operating-system user that launches the service or worker.
- Log or print that process’s
PATH, current user, and working directory. - Run
command -v wkhtmltopdfandwkhtmltopdf --versionfrom that context, not from your personal terminal. - Check that the executable is readable and executable by the service user.
Use an absolute path
If lookup fails but you have verified the binary, configure the integration with its full path. Example locations used by one integration are Linux /usr/bin/wkhtmltopdf, macOS /usr/local/bin/wkhtmltopdf, and Windows C:Program Fileswkhtmltopdfbinwkhtmltopdf.exe. Confirm the actual location with command -v, Finder, or Windows Explorer before entering it.
When an application offers both a “binary path” field and a “PATH” setting, prefer the binary path. It avoids relying on profile scripts and makes the deployment explicit. Restart the service after changing its environment; long-running workers do not automatically reload configuration.
Containers and hardened images
Installing wkhtmltopdf on the host does not install it inside an application container. The executable, shared libraries, fonts, and other runtime files must be present in the image that executes the command. A common integration notes that many n8n Docker images omit wkhtmltopdf by default. Its n8n 2.x guidance also concerns an Alpine-based hardened image where apt-get is unavailable.
Diagnose from inside the container
docker exec -it YOUR_CONTAINER sh
command -v wkhtmltopdf
cat /etc/os-release
wkhtmltopdf --versionUse the shell available in the image; some minimal images have sh but not bash. Read the image’s package documentation before adding installation steps. Debian-based and Alpine-based images use different package managers and library layouts, and a binary compiled for one base image may not run correctly in the other.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Make the fix reproducible
- Add the package installation and required fonts or libraries to the Dockerfile rather than installing manually in a running container.
- Rebuild the image, start a fresh container, and repeat the version check as the application user.
- Do not assume a host-mounted binary has all of the libraries expected by the container.
- Record the selected image architecture (for example, x86_64 or ARM64) and verify that the wkhtmltopdf build supports it.
Verify the executable before debugging PDF output
Once lookup succeeds, separate command discovery from rendering failures:
command -v wkhtmltopdf
wkhtmltopdf --version
printf '<html><body>Smoke test</body></html>' > /tmp/wkhtmltopdf-test.html
wkhtmltopdf /tmp/wkhtmltopdf-test.html /tmp/wkhtmltopdf-test.pdf
ls -lh /tmp/wkhtmltopdf-test.pdfA version string and a non-empty PDF demonstrate that the executable can start and write output. If the lookup succeeds but conversion returns exit code 127 or 139, produces blank output, or reports missing shared libraries or fonts, investigate those runtime issues separately. They are not the original “command not found” condition.
Check permissions and output paths
- The service user must be able to execute the binary and read the input HTML.
- It must be able to create or overwrite the destination directory.
- Use a writable temporary directory when testing; a protected application directory can make a healthy installation look broken.
- Ensure any sandbox, SELinux policy, or container security profile permits the process to launch the binary.
Choose the right remedy for your execution environment
| Where the failure occurs | What to check | Correct remedy |
|---|---|---|
| Interactive local shell | Package presence, shell PATH, executable permission |
Install the package or add its directory to the user’s path |
| Web server or background service | Service user and environment; profile files may not load | Install for the service host and set an explicit binary path or service-level PATH |
| Scheduled job or worker | Job runner’s shell, user, and working directory | Use an absolute path and restart/reload the worker after configuration changes |
| Docker or another container | Package manager, image base, architecture, libraries, fonts | Install and test in the image that runs the command; rebuild it reproducibly |
| Remote VM or build agent | That machine’s image and permissions, not your laptop | Provision wkhtmltopdf as part of the agent setup and verify during deployment |
Common symptoms and targeted fixes
bash: wkhtmltopdf: command not found
The current shell cannot resolve the name. Run command -v, install the package in that shell’s environment, or invoke the verified absolute path.
sh: wkhtmltopdf: not found only in Docker
The container does not contain the executable or its directory is absent from PATH. Inspect /etc/os-release, follow the image’s package instructions, add the dependency to the Dockerfile, and rebuild.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #4
The application says “not installed,” but the terminal finds it
Compare users and environments. Configure the application with the actual binary path, restart the process, and log the path and version from inside the failing service.
Lookup succeeds, but the process exits 127 or 139
Exit 127 or 139, blank output, or messages about libraries and fonts indicate a startup or runtime dependency problem. Check shared-library availability, fonts, architecture, and security policies; do not keep changing PATH after the executable is already found.
A copied directory or binary will not run
Copying files from another machine can leave incompatible libraries, permissions, or architecture. Prefer a package or image build designed for the target operating system, then verify with wkhtmltopdf --version.
Maintenance and renderer choice
The upstream GitHub repository has been archived and made read-only since January 2, 2023. That status does not prevent you from fixing an existing deployment, but it matters when selecting a renderer for a new system: pin a known-good build, test it against your supported operating-system images, and document the binary path and dependencies. Avoid describing an archived project as actively maintained or assuming future operating-system compatibility.
If your immediate requirement is simply a clean PDF or image of a public web page, a hosted capture service can remove the need to manage a browser binary and its libraries. That is a different operational choice from repairing wkhtmltopdf on a private, authenticated rendering pipeline.
Best Value
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. It accepts one GET request and returns PNG, JPEG, WebP, or PDF. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.
For a public URL, the one-call examples below avoid installing wkhtmltopdf or maintaining a browser runtime. See the ScreenshotNeo documentation for all request parameters.
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}`);ScreenshotNeo also supports full-page captures with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets and custom viewports, retina scale, PDF paper size/margins/landscape/page ranges, custom CSS and JavaScript, pre-capture clicks, hidden selectors, selector or delay or network-idle waits, request and resource blocking, custom headers/cookies/user agents/Authorization, timezone and geolocation, transparent backgrounds, image resizing, configurable-TTL caching, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Parameter names used by other screenshot APIs also work.
Recommended Free Tools
The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing provides two months free, and every feature is available on every plan. An MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients. Sign up for the free plan to try it without a card.
Final diagnostic checklist
- Did you run
command -v wkhtmltopdfas the failing process’s user? - Is wkhtmltopdf installed in the VM, container, or host that actually executes it?
- Does
wkhtmltopdf --versionwork in that same context? - Have you configured an absolute path instead of relying on an interactive shell profile?
- Are the binary’s architecture, shared libraries, fonts, permissions, and output directory compatible?
- After changing an image, service, or worker configuration, did you rebuild or restart it?
Frequently Asked Questions
Does installing wkhtmltopdf on my laptop fix a server error?
No. The executable must be installed and callable on the server, worker, VM, or container that runs the failing command.
Should I add wkhtmltopdf to PATH or configure a full path?
A full path in the application is usually more predictable for services and scheduled jobs; use PATH only when you control and test the service environment.
Is a successful version check enough to prove PDF generation works?
No. Follow it with a small conversion test and confirm that the service user can read the input and write the output.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsQuick 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.
