wkhtmltoimage Screenshot Is Too Small: How to Set the Capture Width

Set wkhtmltoimage’s capture width with --width:

wkhtmltoimage --width 1280 input.html output.png

If the page still uses a narrow, mobile-style layout, also try --viewport-size to emulate a wider browser window. These options address different things: --width requests the image capture width, while --viewport-size sets viewport dimensions for layout behavior such as custom scrollbars or CSS overflow. Check the output from your installed build; behavior can vary by package and page.

Set the capture width

Use an integer pixel width appropriate for the image you need. For example:

wkhtmltoimage --width 1280 input.html output.png

The input can be a local HTML file or a URL. For a URL, quote it if it contains shell-special characters:

wkhtmltoimage --width 1440 'https://example.com/' output.png

The command requests a wider capture; it does not guarantee that every build will produce a file with exactly that pixel dimension. Inspect the resulting image and check the installed binary’s help if the setting appears to have no effect.

When to set the viewport too

A wide capture can still contain a narrow layout if the page believes it is being displayed in a narrow browser window. Responsive CSS may select a mobile breakpoint based on the viewport. In that case, try setting a desktop-like viewport as a diagnostic:

wkhtmltoimage --width 1280 --viewport-size 1280x900 input.html output.png

--viewport-size WIDTHxHEIGHT emulates window or viewport dimensions. The official usage documentation describes it for pages where custom scrollbars or CSS overflow depend on the window size. It is not a synonym for capture width, and the documentation does not establish that the two values must always match. Choose viewport dimensions based on the layout you want, then inspect the result.

Choose the right setting

Setting	What it addresses	Try it when
--width <integer>	Requested image capture width	The screenshot itself is too narrow
--viewport-size WIDTHxHEIGHT	Emulated window or viewport dimensions	Responsive layout, overflow, or custom scrollbars depend on window size
--use-xserver with Xvfb	A real X server display setup	A specific legacy Linux setup depends on screen resolution; verify against that package

Diagnose a screenshot that remains small

1. Confirm the output dimensions. Check the actual image file dimensions, not just how it appears in a preview that may scale it.
2. Check the installed command. Run wkhtmltoimage --version and review wkhtmltoimage --help for the options supported by that binary.
3. Compare the page layout. If it is laid out as a phone-sized page, add a suitable --viewport-size and inspect whether a different responsive breakpoint is selected.
4. Check the page itself. Fixed-width containers, CSS transforms, overflow rules, and page-specific responsive styles can make content appear narrow even when the requested capture is wide.
5. Check the package or fork. The upstream repository is archived, so downstream builds can differ. Do not assume all platforms honor options identically.

Linux display-size caveat

A maintainer discussion from 2014 described the then-current Linux headless screen as hard-coded to 800×600, and distinguished viewport size from screen resolution. It mentioned Xvfb with --use-xserver for that setup. This is historical guidance, not a general rule for every current package or platform. Consider it only if you have confirmed that your particular legacy environment depends on a real display size, and verify the behavior with that build.

Common errors and fixes

Symptom	Likely cause	What to do
The output is still narrow	The page layout uses a narrow viewport or fixed-width CSS, or the build handles capture width differently	Try a wider --viewport-size, inspect the page CSS, and check the installed binary’s help and output dimensions.
The page looks mobile-sized inside a wide image	A responsive breakpoint was chosen from the emulated viewport	Set viewport dimensions suited to the intended desktop layout, then capture again.
The option is rejected or ignored	Different or older package, wrapper, or fork	Check --version and --help; confirm you are invoking the expected executable.
Content is clipped or overflows	Viewport-dependent overflow or fixed-size elements	Inspect CSS overflow and try a viewport size that matches the page’s layout needs. Do not assume a larger capture width changes the page’s CSS.
Linux output reflects a small display	A legacy headless display configuration may constrain rendering	Verify the exact environment. The 2014 Xvfb and --use-xserver suggestion applies to the setup discussed there, not necessarily current builds.

Performance, reliability, and cost

Increasing image width increases the amount of output data and can require more memory to render, especially for long pages. Use the smallest width that preserves the detail you need, and avoid capturing at a much larger size than the final display requires. If a command fails intermittently, separate width issues from page-load failures by first capturing a simple local HTML file, then the target page.

wkhtmltoimage uses Qt WebKit, and its upstream repository was archived on January 2, 2023. Package and fork behavior may differ, so pin and document the binary used in a repeatable workflow and check output dimensions when upgrading or changing environments. The research sources do not establish a current cross-platform benchmark or universal reliability guarantees.

Or skip the browser setup

For a hosted screenshot without managing a local rendering binary, ScreenshotNeo takes a URL in one GET request and returns an image or PDF. Its capture options include viewport controls and full-page capture. Cookie banners, newsletter popups, and chat widgets are removed before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server lets AI agents use screenshot tools. ScreenshotNeo is made by Yorker Media; 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.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}`);
const image = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', image));

ScreenshotNeo offers 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Sign up for the free plan.

FAQ

Does --width change the page’s responsive breakpoint?

It requests the capture width. If layout depends on the emulated viewport, test --viewport-size separately.

Should the width and viewport dimensions always match?

No universal requirement is established by the documentation. Matching them is a useful example to try, but choose dimensions based on the target layout and verify the image.

Is the old 800×600 Linux limit universal?

No. It was described in a 2014 maintainer discussion about a particular Linux headless setup and should be treated as historical.

Is wkhtmltoimage still actively maintained upstream?

The upstream repository was archived in January 2023. Check the status and behavior of the specific package or fork you use.