wkhtmltoimage vs Playwright for HTML to Image Conversion

Short answer: For new HTML-to-image automation, start with Playwright when you need current browser automation, selectable browser engines, or flexible screenshot capture. Keep wkhtmltoimage for an established pipeline if it renders your templates acceptably and its older Qt/WebKit foundation is suitable for your maintenance requirements. There is no controlled head-to-head benchmark in the reviewed sources, so choose with representative tests rather than an assumed speed or fidelity winner.

wkhtmltoimage is a command-line HTML renderer based on Qt WebKit. Playwright is a browser automation framework whose Page API can navigate to a page and save a screenshot using Chromium, Firefox, or WebKit. Playwright’s WebKit is not branded Safari, and behavior can vary by operating system. See the wkhtmltopdf project, its status page, and Playwright’s Page API.

1. What differs in practice

Question	wkhtmltoimage	Playwright
Rendering base	Qt WebKit, with project status notes about the age of its Qt/WebKit stack.	Automated browser engines: Chromium, Firefox, or WebKit.
Typical workflow	Pass a URL or HTML input to a CLI and write an image file.	Launch a browser, navigate a page, configure the capture, and write a screenshot.
Capture controls	Command-line conversion suited to existing templates and pipelines.	Documented viewport, element, full-page, and high-resolution screenshot workflows.
Operations	The project describes headless operation without a display service.	Your application or deployment must manage the browser runtime, browser downloads, and platform behavior.
Performance and fidelity	No controlled comparative figures are provided by the reviewed sources.	No controlled comparative figures are provided by the reviewed sources.

The wkhtmltopdf project’s status page says Qt 4 had been unsupported since 2015 and the WebKit in it had not been updated since 2012. Treat those as dated project status statements, not an independent current audit. For a new system, weigh that history against your actual requirements and maintenance plan.

2. Convert a page with wkhtmltoimage

Install a wkhtmltoimage build appropriate for your operating system using the project’s distribution guidance, then verify the executable is on PATH. A basic conversion from a URL is:

wkhtmltoimage https://example.com page.png

For a local HTML file:

wkhtmltoimage ./report.html report.png

Check the installed version and the options supported by that build before adding flags to a production command:

wkhtmltoimage --version
wkhtmltoimage --help

The exact flags available can depend on the packaged build. Set the viewport, output dimensions, quality or format behavior, JavaScript handling, and load timing using options documented by the executable you deploy. Capture a known page and inspect the resulting file; do not assume an option accepted by one package exists in another.

3. Convert a page with Playwright

The following Node.js example is runnable after installing Playwright and its Chromium browser. It navigates to a page, waits for the page load event, and saves a full-page PNG.

npm init -y
npm install playwright
npx playwright install chromium

// capture.mjs
import { chromium } from 'playwright';

const browser = await chromium.launch();
try {
  const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
  await page.goto('https://example.com', { waitUntil: 'load', timeout: 30_000 });
  await page.screenshot({ path: 'page.png', fullPage: true });
} finally {
  await browser.close();
}

node capture.mjs

Playwright’s screenshot API also supports element screenshots, viewport-only captures, and high-resolution output. For example, capture one element after locating it:

const card = page.locator('.report-card');
await card.screenshot({ path: 'report-card.png' });

For Chromium, a device scale factor can be set on the browser context to increase pixel density. Browser options and screenshot options are documented in the Page API and screenshot command documentation.

4. Choosing capture settings

• Viewport or full page: A viewport capture matches the visible browser area. Full-page capture extends to the document height; very long pages may need a deliberate maximum or section-by-section strategy.
• Element capture: Use a locator screenshot when only a chart, card, or component is needed. Ensure the element is visible and stable first.
• Wait behavior: Page load does not guarantee that client-side data, web fonts, or lazy-loaded images have finished. Wait for a meaningful selector or application-ready signal when necessary. Avoid arbitrary long waits where a precise readiness condition is available.
• Browser engine: Choose the engine closest to your production requirement and test on the operating systems you deploy. Playwright WebKit should not be treated as Safari itself.
• Output dimensions: Fix viewport width and device scale factor for repeatable results. Content reflow changes with width, so matching only the output pixel count is insufficient.
• Fonts and assets: Ensure required fonts and remote resources can load in the runtime. Missing fonts or blocked requests can change line wrapping and layout.

5. How to migrate safely

1. Collect representative pages: simple static templates, JavaScript-heavy views, long pages, pages with web fonts, and pages with lazy images.
2. Record the current viewport, output format, dimensions, timing behavior, and any relevant command flags.
3. Capture the same inputs with both tools in the target operating system and deployment environment.
4. Compare layout, typography, image loading, clipping, transparency if applicable, and output file properties. Review differences that matter to downstream users rather than relying on a single visual sample.
5. Measure runtime, memory, startup overhead, and failure rate under the same concurrency and warm/cold conditions. The available sources do not establish a universal speed or resource winner.
6. Run both paths in a limited rollout if output compatibility is critical, then switch only after acceptance criteria pass.

6. Reliability, performance, and cost

Both approaches depend on the page, network, fonts, and runtime environment. Make captures reproducible by controlling the URL or HTML input, viewport, browser version, fonts, wait condition, and output settings. Log the input and failure reason, set navigation and job timeouts, and avoid leaving browser processes open after a capture.

For Playwright, account for browser installation and runtime packaging as part of deployment. Reuse browser processes where the application architecture allows it, while isolating pages or contexts as needed. Validate concurrency and memory behavior with your own workloads. For wkhtmltoimage, verify the packaged binary and its rendering dependencies in the production image. No reviewed source provides a comparative benchmark, so estimate cost from your measured compute, maintenance, and operational requirements.

7. Troubleshooting

Symptom	Likely cause	What to check
Command not found	Binary is not installed or not on PATH.	Check installation and executable path; run wkhtmltoimage --version.
Playwright says browser executable is missing	The browser runtime was not installed for the environment.	Run the Playwright browser install command during image setup and confirm the runtime user can access it.
Blank or partly rendered image	Capture happened before client rendering or remote assets completed, or requests failed.	Wait for a page-specific ready selector; inspect page errors and network access.
Missing images or fonts	Lazy loading, blocked network requests, or unavailable font resources.	Confirm resource URLs are reachable from the capture environment and wait for expected assets.
Different line breaks or clipping	Viewport, device scale, font availability, or engine behavior differs.	Match viewport and fonts; compare the same browser and operating system where possible.
Navigation timeout	The site is slow, hangs on long-lived requests, or the chosen wait event is too strict.	Set a bounded timeout and wait for the actual application-ready condition rather than waiting for unrelated network activity.
Full-page image is unexpectedly huge	The document has a very long or expanding layout.	Inspect document dimensions and capture a target element or bounded sections instead.
Playwright WebKit differs from Safari	Playwright’s WebKit build is not Safari and platform capabilities vary.	Validate with the browser and operating system your users actually need.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Send one GET request with a URL to receive an image or PDF; see the API documentation. This runnable cURL example saves a WebP:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', new Uint8Array(await res.arrayBuffer()));

Cookie banners are accepted like a visitor and removed along with known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report page verdict and billing. An MCP server gives AI agents screenshot, page-info, and PDF tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Start with 1,000 free screenshots a month, no card required.

9. Which should you choose?

• Choose Playwright for a new workflow that needs browser automation, engine choices, or element and full-page capture controls.
• Keep wkhtmltoimage when an existing conversion pipeline is stable, its rendered output meets your needs, and you accept the maintenance implications described by the project’s status page.
• Choose based on evidence when fidelity or speed is decisive: run a controlled comparison with matching inputs, settings, and deployment conditions.

10. FAQ

Is Playwright always faster than wkhtmltoimage?

No. The reviewed official sources do not provide a controlled speed comparison. Measure with your pages and target runtime.

Is Playwright WebKit the Safari browser?

No. It is based on upstream WebKit sources and is not branded Safari; available features can vary by operating system.

Can I keep wkhtmltoimage for a production system?

Yes, if it remains suitable for your templates and environment. Include its project-reported Qt/WebKit age in maintenance planning and test changes before deployment.

What is the most useful migration test?

A representative set of your own pages captured with identical dimensions, waits, fonts, assets, and output expectations in the actual deployment environment.