Give Snappy an absolute path to the actual wkhtmltopdf executable. In Symfony with KnpSnappyBundle, set knp_snappy.pdf.binary in config/packages/knp_snappy.yaml. In standalone PHP, pass the path to new Pdf() or call setBinary(). The same rule fixes most “executable not found” and “The system cannot find the path specified” errors.
Find the executable that your application must run
First identify the file on the machine or container where PHP actually runs. A path that works in your interactive shell may not exist inside PHP-FPM, a queue worker, Docker container or deployment host.
Linux and macOS
command -v wkhtmltopdf
wkhtmltopdf --versioncommand -v prints the resolved executable path, such as /usr/local/bin/wkhtmltopdf. If it prints nothing, install a compatible wkhtmltopdf package or place a trusted binary on the host, then repeat the check.
Windows
Locate wkhtmltopdf.exe in File Explorer or with PowerShell:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesGet-Command wkhtmltopdf.exeA typical installation under Program Files is C:Program Fileswkhtmltopdfbinwkhtmltopdf.exe. The spaces are part of the path; quote the value correctly in YAML or PHP.
Composer-provided binaries
Snappy can point at a Composer-installed executable. The Snappy documentation lists the h4cc/wkhtmltopdf-amd64 and h4cc/wkhtmltopdf-i386 packages, but those static binaries originated from Debian 7 packages and may not work on every Linux distribution. Test the binary and its libraries on the target system before relying on it in production.
Configure KnpSnappyBundle in Symfony
Create or edit config/packages/knp_snappy.yaml:
knp_snappy:
pdf:
enabled: true
binary: /usr/local/bin/wkhtmltopdf
options: []
image:
enabled: true
binary: /usr/local/bin/wkhtmltoimage
options: []The pdf.binary value must be the complete executable path, not just a package name. The image renderer is separate: configure image.binary if your application calls wkhtmltoimage. You can use different locations for the two programs.
Windows YAML path
knp_snappy:
pdf:
enabled: true
binary: "C:\Program Files\wkhtmltopdf\bin\wkhtmltopdf.exe"
options: []
image:
enabled: false
binary: "C:\Program Files\wkhtmltopdf\bin\wkhtmltoimage.exe"
options: []Use a quoted YAML string and escape backslashes as shown. Alternatively, use forward slashes where your Symfony and Windows PHP setup accepts them. Keep the setting in the environment-specific configuration if development and production install the executable in different places.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Clear Symfony’s cached configuration
After changing the file, clear the cache for the environment that renders PDFs:
Rank #2
php bin/console cache:clear --env=prodRestart PHP-FPM, queue workers and long-running consumers when they cache the container at startup. A worker that was started before the configuration change can continue using the old path.
Configure standalone Snappy PHP
When you use knplabs/knp-snappy without the Symfony bundle, provide the path in the constructor:
<?php
use KnpSnappyPdf;
$snappy = new Pdf('/usr/local/bin/wkhtmltopdf');
$pdf = $snappy->getOutputFromHtml('<h1>Invoice</h1>');
file_put_contents(__DIR__ . '/invoice.pdf', $pdf);Or instantiate first and set the binary explicitly:
Free tools Windows power users keep installed
One-click scans. No signup required.
<?php
use KnpSnappyPdf;
$snappy = new Pdf();
$snappy->setBinary('/usr/local/bin/wkhtmltopdf');A Composer-installed executable can be addressed relative to the project:
<?php
use KnpSnappyPdf;
$project = __DIR__;
$snappy = new Pdf(
$project . '/vendor/h4cc/wkhtmltopdf-amd64/bin/wkhtmltopdf-amd64'
);Use the path and filename that actually exist in your vendor directory. Do not assume an amd64 binary is suitable for an ARM host or for every Linux distribution.
Laravel and other integrations
Laravel Snappy packages expose the same underlying binary setting. Set the integration’s binary configuration to an absolute executable path, commonly a vendor/h4cc/.../bin/... path when using a Composer binary. Configuration keys differ between package versions, so check the installed integration’s documentation and confirm the resolved value in the application environment. The important part is unchanged: the Snappy Pdf object must receive the executable path before rendering.
Verify the path as the service account
- Run the exact path with
--versionor-has the same operating-system user used by PHP-FPM, your queue worker or the web server. - Confirm execute permission on the file and traverse permission on every parent directory. On Linux, inspect with
ls -landnamei -l /path/to/wkhtmltopdf. - Render a minimal HTML string before testing templates, remote assets or JavaScript.
- Check that the path is identical in CLI workers, PHP-FPM, scheduled jobs and containers. An interactive shell’s
PATH, current directory and mounted filesystems are not guaranteed to be available to a service.
<?php
use KnpSnappyPdf;
$snappy = new Pdf('/usr/local/bin/wkhtmltopdf');
$html = '<!doctype html><html><body><p>Snappy test</p></body></html>';
$snappy->generateFromHtml($html, __DIR__ . '/snappy-test.pdf');If this creates a PDF, the executable path and basic process launch are working. Failures involving your real page then concern resources, permissions, libraries or rendering options rather than path discovery.
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 →Choose between a system binary and a Composer binary
| Consideration | System-installed executable | Composer-supplied executable |
|---|---|---|
| Portability | Depends on the operating system’s package and repository. | Easy to commit to the project dependency graph, but the static build may not run on every distribution or CPU. |
| Runtime libraries | Usually integrates with libraries, fonts and configuration supplied by the distribution. | May require compatible shared libraries and fonts that are not present in the host image. |
| Upgrades and patches | Managed through the operating system; test package updates in your deployment process. | You control the dependency version and must update and audit it yourself. |
| Container size | Varies with the package and its dependencies. | The vendor binary plus required libraries and fonts can increase the image size. |
| Reproducibility | Pin the OS image and package version to reproduce the same path and behavior. | Lock Composer dependencies and copy the same vendor executable into each image. |
Whichever model you select, configure the resulting absolute path explicitly and test it in the production-like image.
Troubleshoot executable and rendering failures
“Executable not found” or “The system cannot find the path specified”
- The configured path is misspelled, points to a directory, or uses the wrong Windows escaping.
- The package is installed on the host but not in the container or virtual machine running PHP.
- A relative path is resolved from an unexpected working directory.
Copy the path from command -v or the Windows file location, use an absolute value, verify it as the service account, then restart workers and clear the Symfony cache.
Permission denied
Grant execute permission to the file and directory traversal to the service account. Avoid making the entire filesystem writable. In containers, check that the executable is copied into the final runtime stage and retains its mode bits.
Rank #4
It works in a shell but fails in PHP-FPM
PHP-FPM may have a different PATH, environment, current directory, user, mount namespace or security policy. Calling an absolute path removes PATH ambiguity, but you still must make the file and its parent directories visible and executable to FPM.
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 matchThe process starts, then exits with a library or font error
A correctly located binary can still fail when shared libraries, font files or configuration are missing. Bundle compatible runtime libraries and fonts in the deployment image or use a distribution-supported build. Some deployments need environment variables such as LD_LIBRARY_PATH and FONTCONFIG_PATH; set them for the service, not only in your login shell.
Local CSS, images or fonts do not load
wkhtmltopdf can restrict local-file reads. Use explicit, narrow allow paths for trusted, controlled inputs. KnpLabs’ Snappy README warns: “The --enable-local-file-access option in wkhtmltopdf can be risky if used with untrusted HTML or JavaScript.” Never enable broad local access for user-supplied HTML without isolating and validating the input.
Remote assets time out or render blank
Check DNS and outbound network access from the PHP runtime, TLS compatibility, authentication headers and the page’s loading behavior. Test first with a self-contained HTML document, then add external CSS, images and scripts one at a time. A path error is a process-launch problem; a blank or partial document after launch usually requires asset or runtime investigation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your goal is a clean image or PDF of a web page rather than server-side HTML-to-PDF rendering, ScreenshotNeo provides a website screenshot API. 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, and response headers identify the page verdict and billing result. Its MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients.
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 →One-call cURL example (see the ScreenshotNeo documentation for all parameters):
Best Value
- Used Book in Good Condition
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 includes full-page and element capture, device presets and custom viewports, retina scale, dark mode, PDF paper and page controls, custom CSS and JavaScript, clicks, selector waits, delays, network-idle waits, request blocking, headers, cookies, user agents, timezone and geolocation, transparent backgrounds, resizing, selectable cache TTLs, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work, easing migration.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan, and annual billing provides two months free. Create a free ScreenshotNeo account to try it without a card.
Operational checklist
- Use an absolute path to
wkhtmltopdf. - Set
pdf.binaryand, when needed,image.binaryindependently. - Verify the executable as the PHP service user.
- Test a minimal PDF before debugging templates.
- Package compatible libraries and fonts.
- Keep configuration consistent across FPM, CLI, workers and containers.
- Restrict local-file access to trusted inputs and narrow directories.
Frequently Asked Questions
Can I configure only `PATH` instead of `binary`?
You can make the executable discoverable in a service environment, but an explicit absolute `binary` path is more predictable across PHP-FPM, workers and containers.
Do PDF and image generation share one setting?
No. KnpSnappyBundle uses `pdf.binary` for wkhtmltopdf and `image.binary` for wkhtmltoimage.
Why does a valid path still produce a blank PDF?
The process may be launching successfully while failing on missing fonts or libraries, blocked local files, unavailable remote assets or page-loading behavior. Verify those separately with a minimal HTML test.
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.
