How to Fix wkhtmltoimage Not Found in XAMPP on Windows
Fix “wkhtmltoimage is not recognized” in XAMPP by checking the executable, testing its full path, and configuring Windows PATH or PHP correctly.
If XAMPP reports that wkhtmltoimage is not found or “not recognized as an internal or external command,” Windows or the PHP process cannot resolve the executable by that name. First confirm that wkhtmltoimage.exe exists in the bin directory of your wkhtmltopdf installation. Run it using its quoted absolute path. If that works, either add that directory to the existing Windows PATH or configure your PHP application or wrapper to use the full executable path.
The right fix depends on how your application launches the command. A terminal can find a program even when Apache or PHP is running with a different environment or configuration, so test through the failing application after making the change.
1. Find and verify wkhtmltoimage.exe
wkhtmltoimage is a command-line HTML-to-image tool distributed with the wkhtmltopdf project. Its tools render with Qt WebKit and can run headlessly. The executable is commonly in the bin directory beneath the location chosen during installation, but the exact location varies by machine and installer choice.
- Find the wkhtmltopdf installation directory you selected.
- Open its
bindirectory and confirm thatwkhtmltoimage.exeis present. - If it is missing, check whether the package was installed or extracted completely. The project download page lists Windows installer and 7z archive choices for 32-bit and 64-bit systems; select the package appropriate for your machine and verify its contents.
Do not rely on a path copied from another computer or an old forum post. A path such as C:\Program Files (x86)\wkhtmltopdf\bin is an example of one installation, not a guaranteed default.
2. Test the executable by its full path
Open Command Prompt and run the executable with its actual path. Keep the quotes if any directory name contains spaces:
"C:\path\to\wkhtmltopdf\bin\wkhtmltoimage.exe" --versionReplace the example path with the directory you found. If this command launches and prints version information, the binary can run and the original problem is likely command lookup or application configuration. If Windows says the file cannot be found, recheck the path and installation. If the file exists but cannot launch, record the exact Windows error and check that you installed the package for the correct architecture.
3. Choose how PHP should find the executable
| Approach | Use it when | Trade-off |
|---|---|---|
Add the containing directory to Windows PATH |
You want command-by-name invocation to work for processes that inherit this environment. | It affects the environment of processes that receive the updated PATH. Restart relevant processes so they inherit it. |
| Configure the full executable path in your PHP wrapper or application | You can set the executable location for this application and want its configuration to be explicit. | The path is machine-specific and must be updated if the installation moves. |
Use the option your application or wrapper supports. Wrapper documentation commonly supports setting the executable path or making the binary available through PATH; the exact setting name and syntax vary, so consult the documentation for the wrapper actually in use.
Option A: add the bin directory to PATH
- Open Windows environment variable settings and edit the existing
Pathvariable for the account or system scope appropriate to the process. - Add the directory that contains
wkhtmltoimage.exe, for exampleC:\path\to\wkhtmltopdf\bin. Add the directory, not the executable filename. - Preserve the existing PATH entries. Extend the value instead of replacing it.
- Close and reopen Command Prompt. Restart Apache or the process that runs PHP so it receives the updated environment.
- Check command resolution:
where wkhtmltoimage
wkhtmltoimage --versionIf where returns no path, the shell still cannot see the directory. Check that the new entry points to the directory containing the executable, and that you edited the environment scope used by the process.
Option B: set the executable path in the application
Where your PHP wrapper exposes an executable-path option, set it to the full path to wkhtmltoimage.exe, including the filename. For example, the value would have this form:
C:\path\to\wkhtmltopdf\bin\wkhtmltoimage.exeUse the wrapper’s documented configuration method. Do not assume that a setting for wkhtmltopdf.exe automatically configures wkhtmltoimage.exe; they are separate executables. If you store the path in PHP source or a configuration file, use the escaping rules for that context.
4. Check the actual XAMPP and PHP caller
A successful command in your interactive terminal does not prove that the XAMPP application can find it. On Windows, PHP’s exec() launches commands through cmd.exe. Apache may run with a different inherited environment, account, working directory, or application configuration from your terminal.
- Repeat the operation through the page, job, or endpoint that originally failed.
- Inspect the PHP wrapper’s configured binary path and any application-level command construction.
- Confirm which Windows account runs the relevant process and whether its environment includes the PATH change.
- Restart the appropriate XAMPP/Apache process after changing environment variables.
- Use the absolute executable path in application configuration when PATH inheritance is difficult to control.
A temporary diagnostic through the same PHP execution path can help distinguish lookup from application configuration. Keep diagnostics local, avoid exposing server paths in public responses, and remove temporary output afterward:
<?php
$command = '"C:\\path\\to\\wkhtmltopdf\\bin\\wkhtmltoimage.exe" --version';
$output = [];
$status = 0;
exec($command, $output, $status);
var_dump($status, $output);
?>Replace the sample path. This checks whether PHP can launch the absolute executable; it does not capture a page. If it succeeds while the application still fails, inspect the application’s wrapper setting and the exact command it constructs.
5. If XAMPP or wkhtmltopdf was moved
If you moved XAMPP, revisit absolute paths in your scripts and application configuration. XAMPP’s setup script adjusts XAMPP configuration after a move, but user scripts are not adjusted automatically. The same portability issue applies to a hard-coded wkhtmltoimage path: update it if the executable or XAMPP installation moved.
Common errors and fixes
| Symptom | Likely cause | What to check |
|---|---|---|
'wkhtmltoimage' is not recognized as an internal or external command |
The command interpreter cannot find the executable by name. | Confirm the file exists; add its containing directory to PATH or configure the full path. |
| Full-path command also says the file cannot be found | The configured path is wrong, the file is absent, or the package was not installed/extracted where expected. | Browse to the installation’s bin directory and verify the exact filename. |
| It works in Command Prompt but fails in XAMPP | The PHP caller may have a different environment or account, or the application may use another executable setting. | Restart Apache after PATH changes; inspect the wrapper configuration and test through the same PHP caller. |
| It stopped working after moving XAMPP or the binary | A user script or application setting still contains the old absolute path. | Update the configured executable path and other affected user-script paths. |
where wkhtmltoimage returns no result |
The current shell’s PATH does not include the executable’s directory. | Check the edited PATH scope and entry, then open a fresh shell. |
| The executable launches but the application still reports a capture failure | The “not found” problem may be resolved; a separate command argument, input, permissions, or rendering issue may remain. | Capture the exact command and error from the application, then troubleshoot that failure separately. |
Performance, reliability, and security notes
Fixing command lookup only makes the executable available; it does not guarantee that a page will render successfully. The tool must still launch in the PHP process context and load the requested content. For a stable setup, keep the executable path explicit where practical, ensure the relevant process is restarted after environment changes, and verify from the real application caller.
The wkhtmltopdf project’s download page warns against using wkhtmltopdf with untrusted HTML unless user-supplied HTML and JavaScript are sanitized, because it can expose the server to compromise. Treat HTML rendering as a server-side security boundary: do not pass untrusted content directly to the executable. Review the project’s current download and security guidance before choosing a binary; the dossier’s cited stable-version statement is from 2020 and does not establish current release status.
Or skip the browser setup
If your goal is a screenshot rather than maintaining a local renderer, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns an image or PDF. Cookie banners, popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. See the ScreenshotNeo website and API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSign up for 1,000 free screenshots a month, with no card.
FAQ
Is wkhtmltoimage a PHP command?
No. It is a separate command-line executable that PHP applications or wrappers can launch.
Should I add the executable itself or its folder to PATH?
Add the directory containing wkhtmltoimage.exe. For per-application configuration, use the wrapper’s documented setting for the full executable path.
Why does restarting Apache matter after changing PATH?
A running process can retain the environment it inherited when it started. Restart the relevant process so it can receive the updated environment.
Can I use a path from an online example?
Only if that path matches your installation. Verify the executable on your machine rather than assuming an installer chose a universal location.
