npm installs the Node.js wrapper, not the wkhtmltoimage program itself. To convert a URL or HTML into an image, install a native wkhtmltoimage binary for your operating system, verify that wkhtmltoimage --version works, install the wrapper with npm, and make the executable available on PATH or configure its absolute path with setCommand(). The examples below cover URLs, inline HTML, files, options, authentication, local-file access, troubleshooting, and production deployment.
What npm installs—and what it does not
The package named wkhtmltoimage is a Node wrapper around the command-line converter. The native executable does the rendering with its bundled Qt/WebKit engine; npm only gives your JavaScript code an API for launching it.
You therefore need both components:
- A wkhtmltoimage binary version 0.12 or later with patched Qt, installed for your operating system.
- The Node wrapper installed in your project with npm.
The wrapper documentation lists Node.js v4 or later. In practice, use a currently supported Node.js release for security and dependency maintenance, while checking that your selected wrapper still supports it.
Install the binary first
Linux, macOS, or Windows
- Download a prebuilt wkhtmltoimage command appropriate for the operating system and CPU architecture from a trusted distribution source.
- Place the executable in a stable location. Avoid a temporary download directory if a service or CI job will run it.
- Run
wkhtmltoimage --versionin the same shell, container, service account, or CI runner that will launch Node. - Confirm the command prints a version and indicates a patched-Qt build. If the shell says the command is not found, add its directory to
PATHor use the absolute path configuration shown below.
PATH is process-specific. A binary visible in your interactive terminal may be invisible to a systemd service, Docker container, IDE task, or GitHub Actions runner. Test from that exact execution environment.
Recommended Free Tools
#1 Best Overall
Install the wrapper
From your project directory:
npm install wkhtmltoimageThe alternative wkhtmltox package exposes a different API and lets you assign the executable through its converter.wkhtmltoimage property. Choose one wrapper per project and follow its option naming and callback behavior.
Make Node find the executable
Using PATH
If wkhtmltoimage --version works for the Node process, the simplest setup requires no JavaScript configuration:
const wkhtmltoimage = require('wkhtmltoimage');Using an absolute path
When the binary is not on PATH, configure it before calling generate:
const wkhtmltoimage = require('wkhtmltoimage');
wkhtmltoimage.setCommand('/absolute/path/to/wkhtmltoimage');Use the real path for your host. On Windows, provide an escaped path such as C:\tools\wkhtmltoimage\bin\wkhtmltoimage.exe, or use a forward-slash form accepted by your Node environment.
Free tools Windows power users keep installed
One-click scans. No signup required.
Convert a URL to an image
generate accepts either a URL or an inline HTML string and returns a stream. Pipe that stream to a file:
Rank #2
const fs = require('fs');
const wkhtmltoimage = require('wkhtmltoimage');
wkhtmltoimage.generate('https://example.com/', { pageSize: 'letter' })
.pipe(fs.createWriteStream('out.jpg'));The output format is inferred from the filename extension in this example. Use a filename ending in .png, .jpg, or another format supported by your binary build. Treat the write stream as asynchronous: attach error handling in production so a failed renderer or disk write is not mistaken for success.
const fs = require('fs');
const wkhtmltoimage = require('wkhtmltoimage');
const output = fs.createWriteStream('page.png');
output.on('error', (err) => console.error('File error:', err));
wkhtmltoimage.generate('https://example.com/')
.on('error', (err) => console.error('wkhtmltoimage error:', err))
.pipe(output);Write directly with the output option
const wkhtmltoimage = require('wkhtmltoimage');
wkhtmltoimage.generate('https://example.com/', { output: 'out.jpg' });Use either a stream destination or output; a stream is convenient when you need to send bytes to object storage or an HTTP response, while output is straightforward for a local file.
Render inline HTML
Pass an HTML string instead of a URL:
const wkhtmltoimage = require('wkhtmltoimage');
wkhtmltoimage.generate('Hello world
')
.pipe(process.stdout);For repeatable styling, include a complete document and inline CSS. Relative images, stylesheets, and fonts need a resolvable base URL or local-file permissions; otherwise the renderer may produce an image without those resources.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsconst fs = require('fs');
const wkhtmltoimage = require('wkhtmltoimage');
const html = `<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>body{font:16px Arial;margin:24px} .card{color:#123}</style>
</head>
<body><div class="card">Rendered by wkhtmltoimage</div></body>
</html>`;
wkhtmltoimage.generate(html, { output: 'card.png' });Use command-line options from Node
The wrapper maps wkhtmltoimage’s dashed command-line options to camelCase JavaScript properties. The exact accepted names depend on the wrapper and binary, so validate important options against the installed build.
Cookies and custom headers
Cookies and headers let the renderer request authenticated or personalized content. Do not hard-code session secrets in source control.
Rank #3
const wkhtmltoimage = require('wkhtmltoimage');
wkhtmltoimage.generate('https://app.example.test/dashboard', {
cookie: [
['session', process.env.SESSION_COOKIE]
],
customHeader: [
['Authorization', `Bearer ${process.env.API_TOKEN}`]
],
output: 'dashboard.png'
});Option names for repeated values can vary by wrapper version. If an array form is rejected, consult that package’s option mapping and pass the equivalent structure it documents.
Local files and the --allow boundary
wkhtmltoimage can load local resources, but local-file access should be deliberately restricted. The CLI provides --allow <path> and related controls. Allow only the directory containing the HTML and intended assets, not an entire home directory or filesystem.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
const wkhtmltoimage = require('wkhtmltoimage');
wkhtmltoimage.generate('file:///srv/render/index.html', {
allow: ['/srv/render/assets'],
output: '/srv/render/out.png'
});Validate this behavior with the exact binary build used in production. A local-file policy is also a security boundary: untrusted HTML should not be allowed to read application secrets or arbitrary host files.
Cropping and viewport-related options
Crop coordinates change the final image bounds. Use them when you need a region rather than the complete rendered page, and verify the resulting dimensions with representative pages. Page size, width, height, zoom, and quality settings can also affect layout and output size; keep those settings explicit when images are used in visual tests or reports.
Waiting for dynamic content
wkhtmltoimage uses its WebKit-based renderer, not a full modern browser. JavaScript-heavy applications, unsupported CSS, delayed API calls, and web fonts may not finish before capture. Set an appropriate delay or other wait option supported by your wrapper, and test pages that depend on client-side rendering. If a site requires browser features unavailable in the bundled engine, use a current browser automation tool or an image API instead.
Rank #4
Handle completion and failures
The wrapper can accept an optional callback that receives the renderer’s process code and signal. Use it to record failures and to avoid reporting a job as complete before the process exits.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →const wkhtmltoimage = require('wkhtmltoimage');
wkhtmltoimage.generate(
'https://example.com/',
{ output: 'example.png' },
(code, signal) => {
if (code === 0) {
console.log('Screenshot complete');
} else {
console.error('wkhtmltoimage failed', { code, signal });
}
}
);Also monitor stream and filesystem errors. A zero-byte or partially written file is not a valid screenshot even if your application did not throw synchronously.
Equivalent CLI command
The native syntax is:
wkhtmltoimage [OPTIONS]... <input file> <output file>For example:
wkhtmltoimage --width 1280 https://example.com/ example.pngRunning the CLI directly is useful for isolating wrapper problems. If the CLI fails in the same environment, changing JavaScript code will not fix the binary, fonts, permissions, network access, or page itself.
Common errors and fixes
“wkhtmltoimage: command not found” or executable-not-found
- Run
wkhtmltoimage --versionas the same user and from the same service or container. - Print the process PATH and compare it with your interactive shell.
- Install the binary in the image or host that actually runs Node.
- Call
wkhtmltoimage.setCommand('/absolute/path/to/wkhtmltoimage').
With wkhtmltox, set the corresponding converter.wkhtmltoimage property instead.
Blank, incomplete, or unstyled output
- Check that the URL is reachable without an interactive login or blocked certificate.
- Increase the wait period for client-side rendering and confirm that required JavaScript is supported by the bundled WebKit.
- Make relative assets resolvable; for local HTML, configure a narrow
allowdirectory. - Install the fonts used by the page in the runtime environment and compare output from the same binary version.
Authentication does not work
Inspect cookie names, domains, paths, expiration, and header spelling. Ensure secrets are supplied through environment variables and that redirects do not discard the credentials. Capture a non-sensitive test page first to separate authentication errors from rendering errors.
Permission denied or cannot write output
Give the service account write access to the destination directory, use a unique temporary filename, and check available disk space. In containers, verify that the destination is not a read-only mount.
Process hangs or times out
Look for pages waiting on never-ending network requests, JavaScript timers, unreachable assets, or proxy configuration. Enforce an application-level timeout, terminate the child process when it expires, and log the URL and renderer arguments without logging credentials.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Production deployment checklist
- Pin and document the wkhtmltoimage binary build, wrapper version, Node.js version, and installed fonts.
- Run a startup health check that executes
wkhtmltoimage --version. - Keep the executable available in every worker, container, and CI image.
- Restrict local-file access with an allowlist and sanitize untrusted HTML.
- Set request, render, and child-process timeouts; limit concurrency so workers do not exhaust CPU or memory.
- Use deterministic output settings for visual tests: viewport, crop, zoom, format, quality, and wait behavior.
- Record exit codes, signals, render duration, output size, and a redacted target identifier.
- Test redirects, TLS certificates, cookies, custom headers, slow pages, missing fonts, and pages with unsupported modern CSS.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF, so you do not install a native renderer or manage fonts and PATH. It accepts cookie and 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, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
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}`);See the ScreenshotNeo API documentation for parameters and response headers. The Free plan includes 1,000 screenshots each month without a card; paid plans start at $5 for 3,000 screenshots, and every feature is included on every plan. Create a free ScreenshotNeo account.
When wkhtmltoimage remains the right choice
Keep wkhtmltoimage when you need an on-premises executable, deterministic local-file rendering, or an existing pipeline built around its CLI options and patched-Qt output. Choose a hosted API when you want to avoid binary installation, browser-environment maintenance, and per-worker font or PATH drift. For modern, JavaScript-intensive sites, evaluate the actual pages you must capture rather than assuming either tool will render every feature identically.
Frequently Asked Questions
Does npm install wkhtmltoimage install wkhtmltoimage itself?
No. It installs the Node wrapper. Install the native wkhtmltoimage executable separately and put it on PATH or configure its absolute path.
Can the wrapper render an HTML string instead of a URL?
Yes. Pass the inline HTML string to generate; it returns a stream that you can pipe to a file or another destination.
How do I use a binary outside PATH with wkhtmltox?
Set the alternative package’s converter.wkhtmltoimage property to the executable’s absolute path before starting a conversion.
Why are local images missing from my screenshot?
The renderer may not be allowed to read their directory or may not resolve relative paths. Use a narrowly scoped allow path and test the file URLs and asset locations.
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.
