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 matchWindows 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 reinstallnpm installs a Node.js wrapper, not the wkhtmltoimage program itself. To generate images successfully, install a wkhtmltoimage binary with patched Qt, verify that wkhtmltoimage --version works, and make the executable available on PATH or configure its absolute path. Then the wkhtmltoimage package can render a URL or inline HTML and return a stream that you save to PNG, JPEG, or another format supported by your binary.
This guide covers installation on a development machine, servers, containers and CI, complete Node.js examples, command-line options, security boundaries, diagnostics and a managed alternative.
What npm does—and what it does not do
The package named wkhtmltoimage is a JavaScript interface around the native command-line converter. Installing it with npm does not download or compile the native executable for you. Your runtime needs both parts:
- The Node wrapper, installed with
npm install wkhtmltoimage. - A matching
wkhtmltoimageexecutable (version 0.12 or later with patched Qt is the documented baseline).
The executable must be discoverable in the same environment that starts Node. A shell may have a different PATH from a systemd service, Docker container, serverless runtime or CI worker.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
Prerequisites and version checks
- Install Node.js and npm for your application.
- Install a prebuilt wkhtmltoimage binary appropriate for your operating system. Use the package supplied by your OS or an official wkhtmltox build, and make sure its dependencies and fonts are present.
- Run
wkhtmltoimage --version. Confirm that the command returns a version instead of “command not found” and note whether the build reports patched Qt. - Check the Node process sees the same command:
node -e "const {execFileSync}=require('child_process'); console.log(execFileSync('wkhtmltoimage',['--version'],{encoding:'utf8'}))".
The original wrapper documents Node.js 4 or newer. That is a historical minimum, not a recommendation for a new service; use a currently supported Node.js release and test the native binary on the exact operating system used in production.
Install the wrapper with npm
From your project directory:
npm install wkhtmltoimageKeep the package in the dependency set used by deployment (normally dependencies, not only a developer-only group), because production code must be able to require it.
Alternative wrapper: wkhtmltox
wkhtmltox is another Node API. Its documented requirements are Node.js 4 or later and wkhtmltoimage 0.12 or later with patched Qt. Install it separately when you need that API:
npm install wkhtmltoxThe two wrappers do not manage the native executable identically. The original wrapper uses setCommand; wkhtmltox exposes a converter property for the binary path. Choose one wrapper per application and pin versions after testing.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesConfigure the executable path
When wkhtmltoimage is on PATH
If the version check succeeds in the launching environment, no path setting is needed:
const wkhtmltoimage = require('wkhtmltoimage');When it is installed elsewhere
Set an absolute path before calling generate:
const wkhtmltoimage = require('wkhtmltoimage');
wkhtmltoimage.setCommand('/absolute/path/to/wkhtmltoimage');Use the real path for your host, container or packaged application. Avoid a relative path: service working directories often differ from your interactive shell.
Path configuration with wkhtmltox
With the alternative package, configure the converter’s wkhtmltoimage property using the absolute executable path documented by that package. Do not assume setCommand exists on both APIs.
Rank #2
Render a URL to an image
generate accepts a URL or inline HTML and returns a readable stream. This complete example writes a JPEG and reports process failures:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
const fs = require('fs');
const wkhtmltoimage = require('wkhtmltoimage');
async function main() {
const output = fs.createWriteStream('example.jpg');
const image = wkhtmltoimage.generate('https://example.com/', {
format: 'jpg'
});
image.on('error', (err) => {
console.error('wkhtmltoimage failed:', err);
process.exitCode = 1;
});
output.on('error', (err) => {
console.error('Could not write image:', err);
process.exitCode = 1;
});
output.on('finish', () => console.log('Wrote example.jpg'));
image.pipe(output);
}
main();The wrapper also supports the documented direct-output form:
const wkhtmltoimage = require('wkhtmltoimage');
wkhtmltoimage.generate('https://example.com/', { output: 'out.jpg' });Use a URL that is reachable from the machine running the binary. A URL that works in your laptop browser may fail from a private subnet, container or CI runner.
Render inline HTML
Pass an HTML string instead of a URL. Include a complete document when you depend on styles, character encoding or a predictable viewport:
const fs = require('fs');
const wkhtmltoimage = require('wkhtmltoimage');
const wkhtmltoimage = require('wkhtmltoimage');
const html = `<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
body { font-family: Arial, sans-serif; margin: 32px; }
.card { width: 640px; padding: 24px; background: #f3f4f6; }
</style>
</head>
<body><div class="card"><h1>Hello world</h1></div></body>
</html>`;
wkhtmltoimage.generate(html, { output: 'inline.png' });For an HTML string that references local files, use explicit file permissions and paths rather than broadly enabling access to the whole filesystem.
Recommended Free Tools
Write to stdout or choose an output format
The stream can be piped anywhere, including standard output:
const wkhtmltoimage = require('wkhtmltoimage');
wkhtmltoimage.generate('<h1>Hello world</h1>').pipe(process.stdout);The filename extension and wrapper options determine the requested output. A typical call is:
Rank #3
wkhtmltoimage.generate('https://example.com/', {
output: 'out.webp'
});Confirm that your installed binary supports the format you request. If a format is rejected, select PNG or JPEG and inspect the process error.
Important options and their security boundaries
The wrapper maps command-line switches to camelCase option names. Option availability can vary by binary build, so validate each option against the version deployed in production.
Free tools Windows power users keep installed
One-click scans. No signup required.
Page size, viewport and cropping
pageSize: 'letter'selects a paper-style size where supported.- Cropping coordinates and width/height options change the image bounds; they do not merely scale the same canvas.
- Use the binary’s viewport and zoom-related options when responsive layout must be reproduced. Test at the exact dimensions used by your consumers.
Cookies and custom headers
Cookies can select a logged-in or personalized view. Custom headers can provide authorization or API context. Treat these values as secrets: do not put tokens in public URLs, logs or untrusted HTML, and isolate jobs that handle different users.
Local files and --allow
The CLI provides --allow <path> and related local-file controls. Grant only the directories required for images, CSS and fonts. A broad local-file allowance can expose server files if an attacker controls the HTML or URL.
Proxy and network controls
Proxy settings affect DNS, routing and authentication. Configure them in the job environment rather than accepting arbitrary proxy values from request parameters.
Waiting and dynamic pages
wkhtmltoimage is an older WebKit-based renderer. Pages that rely on modern JavaScript, long-running requests or browser APIs may render incompletely. Where the binary offers delay or JavaScript controls, use the smallest deterministic wait and test for missing fonts, charts, lazy images and client-side navigation.
Using the wkhtmltox API
If you choose wkhtmltox, its API names differ from the original wrapper. A representative structure is:
Rank #4
const fs = require('fs');
const wkhtmltox = require('wkhtmltox');
const converter = wkhtmltox();
converter.wkhtmltoimage = '/absolute/path/to/wkhtmltoimage';
converter.image('https://example.com/', { format: 'png' })
.pipe(fs.createWriteStream('out.png'));Check the installed package’s API before copying this into production; the key distinction is that the converter property, not setCommand, controls binary discovery.
CLI equivalent for debugging
Running the native command directly separates wrapper problems from rendering problems. Its general form is:
wkhtmltoimage [OPTIONS]... <input file> <output file>For example, render a local HTML file:
wkhtmltoimage --allow /srv/site/assets /srv/site/index.html /tmp/index.pngUse the CLI help for the exact spelling supported by your build. The documented option families include cookies, custom headers, proxy controls, cropping coordinates and local-file allowlists. Once the CLI works, reproduce the same values in camelCase through the Node wrapper.
Troubleshooting: symptoms, causes and fixes
“wkhtmltoimage: command not found” or executable-not-found errors
- Cause: the binary is absent, not executable, or outside the Node process’s
PATH. - Fix: run
wkhtmltoimage --versionas the same user; printprocess.env.PATH; then install the binary, correct permissions, or callsetCommand('/absolute/path/to/wkhtmltoimage').
The command works in a shell but fails in a service or CI job
Services often receive a minimal environment. Set PATH in the service definition or use an absolute path. Ensure the binary and shared libraries are included in the container image and that the working user can execute it.
Blank, partial or outdated output
- Check that the target URL is reachable from the runtime and that DNS, TLS and proxy settings are valid.
- Allow enough time for assets and JavaScript, but avoid unbounded waits.
- Inspect remote font, image and stylesheet URLs; a browser cache on your desktop can hide failures.
- Test the same URL with the CLI and record the binary version.
Local images or CSS do not load
Use an explicit --allow directory (or its wrapper equivalent), reference files with valid paths, and verify permissions. Do not enable unrestricted local-file access for untrusted input.
Authentication or personalization is missing
Supply the required cookies and headers in the option object, confirm that they are sent to the correct host, and ensure redirects do not move the request to a host that does not receive them. Remove secrets from debug output.
Unsupported modern web features
Legacy WebKit may not implement current CSS, JavaScript syntax or browser APIs. Simplify the page for this renderer, pre-render data into HTML, or use a maintained browser-based screenshot service when fidelity to a modern browser is required.
The output file is empty or truncated
Listen for stream and write-stream errors, wait for the output stream’s finish event, and avoid terminating the process immediately after calling pipe. Check disk permissions and available temporary space.
Reliability, performance and deployment practices
- Warm-up: launching a native process per request adds startup cost. Queue work and cap concurrency so CPU, memory and file descriptors remain available.
- Isolation: run untrusted URLs and HTML in a restricted account or container. Limit local-file access, outbound network access and job duration.
- Determinism: pin the wrapper and binary versions, install the same fonts in every environment, and set an explicit locale, timezone and viewport when visual output is compared.
- Observability: log URL host, duration, exit code, binary version and option profile, but redact cookies, authorization headers and page contents.
- Retries: retry transient network failures with a bounded backoff; do not blindly retry invalid HTML, missing binaries or authentication errors.
- Storage: write to a temporary file or stream and atomically rename completed output. Clean up failed artifacts.
Or skip the browser setup
If maintaining a native renderer, fonts and OS packages is not a good fit, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners before capture 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 response headers identify the page verdict and billing status.
One GET request returns PNG, JPEG, WebP or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the complete parameter list and options in the ScreenshotNeo documentation. The service also supports full-page capture with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets or any viewport, retina scale, PDF paper and page controls, custom CSS and JavaScript, pre-capture clicks, hidden selectors, waits for selectors, delays or network idle, ad/tracker/request blocking, custom headers, cookies, user agents and Authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API and an OpenAPI specification. Common screenshot-API parameter names are accepted to ease migration.
An MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
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 →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →When to choose each approach
| Need | wkhtmltoimage with npm | ScreenshotNeo |
|---|---|---|
| Render local HTML and files inside your own network | Suitable when you control the host and configure --allow carefully. |
Designed for reachable web URLs rather than arbitrary private filesystem paths. |
| Modern browser fidelity and cleanup | Legacy WebKit may require page-specific workarounds. | Removes consent banners, popups and chat widgets before capture. |
| Operations | You maintain binaries, fonts, dependencies, queues and isolation. | Use an HTTPS API or MCP tools; failed loads and bot checks are not billed. |
| Cost entry point | Software is self-hosted; infrastructure and maintenance are yours. | 1,000 shots monthly free with no card; paid plans start at $5 for 3,000. |
Frequently Asked Questions
Does npm install wkhtmltoimage install the executable?
No. It installs the Node wrapper. Install wkhtmltoimage separately and put it on PATH or configure its absolute path.
How can I verify which binary Node is using?
Run the version command from the same user and environment that launches Node, or configure and log the explicit absolute path with setCommand.
Can wkhtmltoimage capture an HTML string instead of a URL?
Yes. Pass the string to generate; the wrapper returns a stream that can be piped to a file or stdout.
Why are local assets blocked?
Local-file access is restricted unless you allow the required directory. Add a narrow –allow path and check permissions.
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.
