How to Save a Transparent PNG with wkhtmltoimage

To save a transparent PNG with wkhtmltoimage, specify PNG output and pass --transparent:

wkhtmltoimage --format png --transparent input.html output.png

The option makes the renderer’s white background transparent in PNG output. It does not automatically remove an opaque background painted by your HTML or CSS, and it does not extract a foreground object from a page. The documented setting applies to PNG or SVG; use --format png when you need a raster PNG. See the libwkhtmltox image settings reference and the wkhtmltoimage command-line option source.

Command-line usage

Pass the input HTML or URL first and the output filename second. Use a .png output filename and explicitly request PNG format:

wkhtmltoimage --format png --transparent ./input.html ./output.png

You can also render a web page by URL:

wkhtmltoimage --format png --transparent https://example.com ./page.png

The input may be local HTML or a URL that the renderer can load. If you are converting a local file, use a path the process can read. For repeatable builds, record the installed wkhtmltoimage version alongside your command, since behavior can depend on the packaged build.

What the transparency option changes

The option targets the renderer’s default white background. It is not a CSS background-removal feature. If a page sets an opaque background on html, body, or a full-size wrapper, that painted content can remain visible in the output. To obtain transparent areas, make sure the relevant page regions do not paint an opaque color.

For example, inspect styles such as:

html, body {
  background: white;
}

.canvas {
  background-color: #fff;
}

Remove or adjust those background declarations only where transparency is intended. Keep backgrounds on elements whose color should remain in the image.

Verify that the saved PNG has alpha

PNG transparency is easiest to judge over contrasting backgrounds. Open the file in an alpha-aware image viewer, or composite it over both a light and a dark background. A white-looking preview alone does not prove that the image is opaque: transparent pixels can appear white against the viewer’s canvas.

1. Confirm the output file is the expected PNG.
2. Open it in a viewer that displays transparency, often with a checkerboard pattern.
3. Place or preview it over a dark background and a light background.
4. Check whether the page’s own CSS painted the areas that you expected to be transparent.

These checks distinguish transparent pixels from white pixels and make edge artifacts easier to spot.

Common problems and fixes

Symptom	Likely cause	What to check
The output background is opaque white	The flag is missing or unsupported by the installed command, output format is not PNG, or the page itself paints a white background.	Run wkhtmltoimage --help, specify --format png --transparent, and inspect html, body, and wrapper CSS.
The image looks white in one viewer	The viewer may show transparent pixels against white.	Use an alpha-aware viewer or composite the PNG against a dark contrasting color.
Transparent areas contain scattered noise pixels	A build-specific rendering issue is possible.	Compare the same image over light and dark backgrounds, record the exact build, and check whether another available build behaves differently.
Colored edges or halos appear	The available issue reports do not establish one general cause for all edge artifacts.	Inspect the image over contrasting backgrounds and isolate the page content and CSS that produce the edge before attributing it to transparency handling.

The project issue tracker includes reports of random noise in transparent PNGs. One discussion proposes initializing the image buffer with transparent pixels as a source-level remedy, but that report does not establish that every released binary includes the change. Treat it as a possible build-specific problem rather than a guaranteed fix: issue #4267 and issue #2629.

Reliability and performance notes

The cited project material documents the transparency option and individual noise reports, but does not provide a quantified reliability rate or comparative performance data. Check the exact binary used in your environment and inspect representative output, especially if transparent PNGs are generated in a production pipeline.

For predictable output, keep the command explicit, avoid accidental CSS backgrounds, and validate alpha on a sample from each renderer build or deployment environment. The transparency flag itself does not guarantee that page content will finish loading or that every build will produce identical pixels.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF; use its API documentation for the complete options and response details.

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

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.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', res);

These examples request a WebP image, not a transparent PNG. ScreenshotNeo’s documented product facts here do not establish a transparency option, so use the wkhtmltoimage method above when alpha transparency is required. ScreenshotNeo removes cookie banners, popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed; its MCP server lets AI agents take screenshots; and 1,000 screenshots per month are free with no card, with paid plans starting at $5 for 3,000.

Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does --transparent remove a white background set in CSS?

It is documented as making the renderer’s white background transparent. It is not documented as erasing an opaque CSS background; inspect the page styles if the result stays white.

Can I use this option when I need a vector image?

The settings reference describes transparency for PNG or SVG. This guide requests PNG because its goal is a raster PNG.

Why do transparent PNGs sometimes show speckles?

There are project issue reports of random noise pixels in transparent PNGs. The reports concern particular cases and do not show that every build is affected.