Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If pdfkit reports No wkhtmltopdf executable found, install a wkhtmltopdf build that matches your operating system and CPU architecture, then either put it on the process’s PATH or configure pdfkit with its absolute path. pdfkit is a wrapper; wkhtmltopdf is the separate executable it must launch. A path that works in your terminal may not be visible to a web worker, cron job, or container.
Why pdfkit cannot find wkhtmltopdf
Python’s pdfkit and Ruby’s PDFKit do not render PDFs by themselves: they invoke the wkhtmltopdf executable. The error means the wrapper could not locate or launch that executable using its current configuration. Common causes are that wkhtmltopdf is not installed, its directory is not on PATH, or the application process has a different PATH from your login shell. A binary can also exist at the expected location but fail to run because it is incompatible with the host or lacks runtime dependencies.
The Python project documents IOError: 'No wkhtmltopdf executable found' for an executable missing from PATH or custom configuration. See the Python pdfkit project and its configuration documentation. Ruby PDFKit documents its own executable-path setting at the Ruby PDFKit project.
Recommended Free Tools
Find out whether the executable is installed and discoverable
Check PATH on your operating system
Run the command in the same environment where the failing application runs, if possible:
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
- Linux or macOS:
which wkhtmltopdf - Windows Command Prompt or PowerShell:
where wkhtmltopdf
If a full path is printed, note it for the configuration step. If no path is printed, the executable is either absent or its containing directory is not on the current PATH. A successful lookup in your interactive shell does not prove that a service or scheduled job can find it.
Test the executable directly
When discovery succeeds, run:
wkhtmltopdf --version
Then try a simple conversion outside pdfkit. For example, save a small HTML page as test.html and run:
wkhtmltopdf test.html test.pdf
If the command itself fails, troubleshoot the binary or its runtime environment before changing wrapper code. If it works directly but pdfkit fails, focus on the configuration and the environment seen by the Python process.
Install a build that matches the host
Use a system package when it is available for your distribution and fits your maintenance requirements, or obtain an upstream platform build from the wkhtmltopdf downloads page. The project’s download materials list Windows, macOS, and Debian builds with architecture qualifiers; choose the build for the actual host architecture, not merely the architecture of the machine you used to download it.
The project lists stable series 0.12.6, released June 11, 2020. That release information does not guarantee that a particular package is available or maintained for every current operating system. Check your distribution’s package availability and the upstream build’s platform requirements before choosing an installation method.
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
The installation wiki describes downloading a static binary for the architecture, extracting it, and placing it in a directory on PATH: wkhtmltopdf installation guidance. “Static” does not mean every runtime dependency can be ignored: the project notes that execution can depend on installed fonts, fontconfig, and freetype2.
Account for libc and runtime dependencies
Check the host’s C library as well as its operating system and CPU architecture. In particular, a generic glibc binary is not suitable for Alpine Linux’s musl environment. A binary that exists but exits immediately, reports a missing library, or crashes may be a platform mismatch rather than a pdfkit path problem. Confirm that the build and required runtime dependencies match the target environment.
Configure Python pdfkit with an explicit path
If you know where the executable is, pass its absolute path to pdfkit. Replace /opt/bin/wkhtmltopdf with the path returned by your system or the location where you installed it:
import pdfkit
config = pdfkit.configuration(wkhtmltopdf='/opt/bin/wkhtmltopdf')
pdfkit.from_string(html_string, output_file, configuration=config)Here, html_string must contain the HTML you want to convert, and output_file must be a valid destination path for the application. Keep the configuration object in the code path that performs the conversion; creating it without passing it to from_string will not change which executable is launched.
For a URL or an HTML file, the same configuration object can be passed to the corresponding pdfkit conversion function. The key fix is the wkhtmltopdf absolute path in pdfkit.configuration().
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
Configure Ruby PDFKit with an explicit path
In a Ruby application using the PDFKit gem, set the executable path in its configuration:
Outdated 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 matchPC 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 & 11PDFKit.configure do |config|
config.wkhtmltopdf = '/path/to/wkhtmltopdf'
endReplace the example with the actual absolute path on the deployed host. The Ruby project documents this configuration pattern at PDFKit on GitHub.
Choose between PATH discovery and an absolute path
| Approach | Best fit | What to watch |
|---|---|---|
Find wkhtmltopdf through PATH |
Local development or a controlled environment where the same PATH is set for the app and terminal. | Services, workers, cron jobs, and containers may receive a different PATH. |
| Configure an absolute executable path | Deployed applications or any environment where PATH may vary. | The path must exist on every host or container running the app, and the binary must be executable there. |
An explicit path is generally the more reliable option when diagnosing a shell-versus-service discrepancy. It avoids relying on how the process manager constructs PATH, but it does not solve an incompatible or non-runnable binary.
Diagnose wrapper errors separately from wkhtmltopdf errors
“No wkhtmltopdf executable found”
Check whether which or where finds the executable from the relevant environment. If it does not, install it or add its directory to the process’s PATH. If it does, pass the returned absolute path through pdfkit’s configuration. Python pdfkit documents both PATH discovery and custom configuration as the places to check for this error.
“Command Failed” or a conversion that exits unsuccessfully
Python pdfkit recommends running the generated command directly and enabling verbose=True to expose wkhtmltopdf’s output. For example:
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
import pdfkit
config = pdfkit.configuration(wkhtmltopdf='/opt/bin/wkhtmltopdf')
pdfkit.from_string(
'<html><body>PDF check</body></html>',
'test.pdf',
configuration=config,
verbose=True,
)Use the command shown by the error to reproduce the failure outside the wrapper. A segmentation fault, missing shared library, or other wkhtmltopdf-level message points to the executable or runtime dependencies, not simply pdfkit’s ability to find a file. The Python project’s debugging guidance covers direct command execution and verbose output.
It works in a terminal but not in the app
Compare the environment and user account for the successful shell with those used by the service, cron job, worker, or container. The application may have a shorter or entirely different PATH, may run under a different account, or may be in a filesystem where the binary is absent. Set an absolute path in the wrapper and ensure that the executable and its dependencies exist in the runtime environment.
The file exists but will not execute
Confirm the CPU architecture and operating-system compatibility, then check libc and the fonts, fontconfig, and freetype2 runtime requirements. If the target is Alpine, do not assume a generic glibc build will run under musl. Test wkhtmltopdf --version in the actual deployment image or host to see whether the binary starts there.
Security: do not convert untrusted HTML without safeguards
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 it is running on!” The warning appears on its official downloads page. Treat HTML and JavaScript supplied by users as untrusted input; do not pass it to wkhtmltopdf without appropriate sanitization and security controls.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsOr skip the browser setup
If your goal is a clean image or PDF capture of a web page rather than running wkhtmltopdf locally, ScreenshotNeo is a website screenshot API and MCP server. It is separate from pdfkit and wkhtmltopdf: it accepts a URL in an API request and returns a PNG, JPEG, WebP, or PDF. Its capture flow can accept cookie or consent banners like a visitor and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, with the response identifying the page verdict and billing status in headers. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf.
For an API key and parameters, see the ScreenshotNeo API documentation. This cURL example captures a page to WebP:
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe Python equivalent is:
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)Or use 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’s free plan includes 1,000 shots per month with no card required; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo and get 1,000 free screenshots a month, with no card.
Frequently Asked Questions
Does installing pdfkit also install wkhtmltopdf?
No. pdfkit is the wrapper; wkhtmltopdf is the separate executable it needs to launch.
Why does `which wkhtmltopdf` return a path while my application still reports it missing?
The command may have been run in a shell whose PATH differs from the application process. Configure the wrapper with the executable’s absolute path and ensure it exists in the application’s runtime environment.
What should I check if wkhtmltopdf is found but immediately crashes?
Run it directly in the target environment, then verify architecture, libc compatibility, and runtime dependencies such as fonts, fontconfig, and freetype2.
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.
