wkhtmltoimage Command Line Options for Screen Size and Viewport

Use --width and --height to set wkhtmltoimage’s screen dimensions. Width is a guideline by default; add --disable-smart-width when you need the specified width to stay strict. Height defaults to a value calculated from page content. To capture only a region, use the separate crop options: --crop-x, --crop-y, --crop-w, and --crop-h. These control the captured rectangle, not the page’s render dimensions. Ubuntu’s wkhtmltoimage manpage documents these options.

Set screen width and height

For a 1200-pixel render width and an 800-pixel screen height:

wkhtmltoimage --width 1200 --disable-smart-width --height 800 input.html output.png

Replace input.html with a local HTML file or URL, and choose an output filename with an appropriate image extension. The width controls the screen used to render the page. The height sets the screen height; omitting it lets wkhtmltoimage calculate height from the content.

Use a width without disabling smart width when you want the renderer to accommodate unbreakable content that exceeds the requested width:

wkhtmltoimage --width 1200 input.html output.png

In the Debian implementation documentation, --disable-smart-width makes the specified width apply even when it is too small for the content, while --enable-smart-width allows the width to extend to fit unbreakable content. The default behavior may depend on the installed build, so check its help output if the result matters.

Render dimensions and crop dimensions are different

Set render dimensions to influence how the page lays out. Set crop coordinates and dimensions to select the rectangle included in the capture. For example, render at a strict width of 1200 pixels and capture a region starting at the upper-left corner with a 1200-by-800 crop:

wkhtmltoimage --width 1200 --disable-smart-width --crop-x 0 --crop-y 0 --crop-w 1200 --crop-h 800 input.html output.png

The crop options are --crop-x and --crop-y for the origin, and --crop-w and --crop-h for crop width and height. A crop does not make the page adopt a responsive layout at those dimensions; set the screen size separately if that is the goal.

These options define controls, not a guarantee that every page will produce an image with exactly the requested final dimensions. Content overflow, page layout, and build-specific behavior can affect the result. Inspect the output for your input and installed binary.

There is no documented wkhtmltoimage --viewport-size option

Do not assume --viewport-size is an image command option. The checked project usage documentation lists that option for wkhtmltopdf; the cited wkhtmltoimage reference documents --width and --height instead. Confirm against your installed binary with wkhtmltoimage --help or wkhtmltoimage --extended-help, since distributions and builds can differ.

Choose the right geometry options

Goal	Options	What they control
Choose the page’s render width	--width	Screen width used during rendering; a guideline by default in the cited manpage.
Keep the specified width strict	--width and --disable-smart-width	Prevents smart width from expanding to fit content, as described in Debian’s implementation documentation.
Allow width to fit unbreakable content	--enable-smart-width	Allows width to extend for unbreakable content in the cited Debian implementation.
Choose screen height	--height	Screen height; otherwise calculated from page content.
Capture a selected rectangle	--crop-x, --crop-y, --crop-w, --crop-h	Crop origin and dimensions, separately from screen dimensions.

Troubleshoot unexpected output

Symptom	Likely cause	Fix
Output is wider than the requested width	Width is a guideline, or smart width expands for unbreakable content.	Add --disable-smart-width and inspect whether the page has wide, unbreakable content. Check the installed build’s help.
Page layout does not match the intended viewport	The render screen size was confused with crop size, or a PDF-specific option was used.	Set --width and optionally --height for rendering. Use crop options only to select the capture rectangle.
Image height differs from the requested crop height	Screen height and crop height are separate controls; page content and build behavior can also affect output.	Set --height for the screen, then set --crop-h for the desired crop and verify the resulting file.
Unknown long argument --viewport-size	The installed wkhtmltoimage build does not expose that option; the referenced usage documentation associates it with wkhtmltopdf.	Use the image command’s width and height options and confirm available flags with --help or --extended-help.
Flags or behavior differ across machines	Packaged versions and builds can differ.	Record the binary version and compare local help output with documentation for that build. The cited Ubuntu Noble manpage covers package version 0.12.6-2build2.

Performance, reliability, and cost considerations

The cited references provide no relevant benchmark or performance statistic, so there is no substantiated speed claim to make about a particular width or height. Larger render areas and complex pages may require more work, but measure your own workload rather than assuming a specific cost or runtime. For repeatable captures, pin the wkhtmltoimage build, use explicit geometry, and validate representative pages, especially those with wide content or long pages.

wkhtmltoimage is a command-line program you run in your own environment; account for the compute, maintenance, and operational work of running it there. If you need a managed screenshot request instead, ScreenshotNeo offers a website screenshot API and MCP server. Its plans and per-response billing indicators are described below.

Or skip the browser setup

ScreenshotNeo takes a URL in one API request and returns an image or PDF. See the ScreenshotNeo API documentation for its options.

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}`);

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed. Responses identify the page verdict and billing status in X-Page-Verdict and X-Billed headers. Its MCP server includes tools for AI agents to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Learn about ScreenshotNeo, then sign up for 1,000 free screenshots a month with no card.

FAQ

How do I set a fixed width and height?

Use --width and --height; add --disable-smart-width if the width must remain strict.

Why is my image bigger than the dimensions I requested?

Render dimensions and crop bounds are separate, and smart width may allow content to expand the render width. Use strict width if needed and inspect the output.

Does wkhtmltoimage accept --viewport-size?

The cited wkhtmltoimage reference does not list it. The checked project usage documentation lists it for wkhtmltopdf. Check your own binary’s help for build-specific options.

How can I check which options my installed version supports?

Run wkhtmltoimage --help or wkhtmltoimage --extended-help and compare with documentation for that package build.

Sources

• Ubuntu Noble wkhtmltoimage(1) manpage
• Debian wkhtmltoimage implementation options
• wkhtmltopdf project usage documentation