How to set the viewport size in wkhtmltoimage

To control the layout width in wkhtmltoimage, use --width N. The manual describes this width as a guideline; add --disable-smart-width when you need strict width handling. Use --height N to set screen height. If you need the output image to have exact bounds, set the crop with --crop-x, --crop-y, --crop-w, and --crop-h.

--viewport-size is not a general replacement for those options. The option is documented for emulating a window size in cases involving custom scrollbars or CSS overflow; it does not itself set screen resolution. That wording appears in the wkhtmltopdf usage documentation, while the wkhtmltoimage manual documents --width and the crop controls.

1. Choose the dimension you need

Goal	Option	What it controls
Influence the page’s screen or layout width	--width N	A width guideline for rendering.
Make width handling strict	--disable-smart-width	Disables smart-width behavior.
Set screen height	--height N	Height, separate from width and crop bounds.
Define the output rectangle	--crop-x, --crop-y, --crop-w, --crop-h	Crop origin and dimensions.
Emulate a window for the documented overflow/scrollbar use case	--viewport-size	Viewport behavior; not a general screen-resolution control.

First decide whether you mean the width that affects page layout, the height of the rendering area, or the rectangle to include in the final image. These are related but distinct controls. A page can also report screen dimensions that differ from the requested window or viewport.

2. Set a strict width

Run this command from a shell. Replace the URL and output filename as needed:

wkhtmltoimage --width 1280 --disable-smart-width https://example.com page.png

--width 1280 asks the renderer to use a 1280-pixel screen width. The manual describes width as a guideline unless smart width is disabled. If your installed build does not recognize a flag or produces a different result, check that binary’s own help and version: behavior can depend on build and platform.

3. Set height and crop to exact output bounds

When you need an image bounded to a particular rectangle, specify the screen dimensions and crop dimensions explicitly:

wkhtmltoimage --width 1280 --disable-smart-width --height 1024 \
  --crop-x 0 --crop-y 0 --crop-w 1280 --crop-h 1024 \
  https://example.com page.png

The crop origin is measured by --crop-x and --crop-y; the crop dimensions are --crop-w and --crop-h. This example requests a crop starting at the top-left and measuring 1280 by 1024. It describes option usage, not guaranteed output for every build or page. Inspect the resulting image and adjust the crop if the content or renderer’s behavior requires it.

4. When to use --viewport-size

The project’s wkhtmltopdf usage documentation describes --viewport-size as a way to set viewport size when custom scrollbars or CSS overflow need window-size emulation. The option was added in the 0.12.0 changelog. A project issue described a CentOS 6.5 / wkhtmltopdf 0.12.0 environment where a page reported 800×600 despite an attempted 1280×1024 viewport. A maintainer clarified that viewport/window size and screen resolution are different. Treat that report as historical and build-specific, not as a universal limit.

For wkhtmltoimage, the documented screen-width control is --width. If the actual goal is a fixed-size output file, use crop flags as well. If the goal is to change how responsive CSS lays out, focus on the rendering width and verify the page’s layout in the resulting image.

5. Edge cases to account for

• Fixed-width content: A layout width does not force every element to shrink. Fixed-width or otherwise non-flexible content can exceed the available width or be cut off; QtWebKit’s layout notes discuss this limitation.
• Reported screen size: JavaScript that reads screen dimensions may report values distinct from the requested viewport or output crop.
• Height versus crop: --height sets screen height; crop height defines the vertical extent of the output rectangle. They are not interchangeable.
• Build differences: The relevant issue dates from 2014 and concerns a particular Linux environment. Check the installed binary rather than assuming all builds share that behavior.
• Page rendering: Long pages, overflow containers, delayed content, and fixed-position elements may not fit the intended crop in the way you expect. Review the actual image and tune width, height, and crop independently.

6. Troubleshooting

Symptom	Likely cause	What to try
The page still looks wider than requested.	--width is a guideline by default, or the page contains non-flexible content.	Add --disable-smart-width; inspect wide fixed-width elements and the resulting image.
The file dimensions are not the intended rectangle.	Screen dimensions were set without defining output crop bounds.	Set --crop-x, --crop-y, --crop-w, and --crop-h, then inspect the output.
Page JavaScript reports 800×600.	The reported screen resolution can differ from the requested viewport/window; this was reported for a specific historical build.	Check the installed version and platform. Use documented width and crop controls for layout and image bounds rather than treating a reported screen value as proof of the output dimensions.
--viewport-size is rejected or appears to have no effect.	You may be relying on an option documented for wkhtmltopdf’s viewport use case, or using a build with different option support.	Run wkhtmltoimage --help and check the binary version. Use --width for screen width and crop flags for output bounds.
Content is cut off at the sides.	Some content is wider than the available viewport and does not reflow.	Inspect the page’s fixed-width elements, try a larger width, or choose crop coordinates that include the desired area.

7. Performance, reliability, and cost

The cited documentation establishes what the rendering and crop options mean; it does not provide a benchmark for capture speed, reliability, or resource use. Runtime will depend on the page, the local build, and the environment. For repeatable captures, record the wkhtmltoimage version and flags alongside the input URL, and inspect representative output when changing builds or page templates.

Running wkhtmltoimage means operating the renderer in your own environment. That can suit scripts and workflows that already use it. If you would rather make a screenshot request without managing a browser-rendering setup, ScreenshotNeo provides a website screenshot API and MCP server for developers.

Or skip the browser setup

ScreenshotNeo accepts a URL in one GET request and can return PNG, JPEG, WebP, or PDF. Its capture flow accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. See the ScreenshotNeo 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}`);

Use YOUR_API_KEY from your account and choose a target URL. The API also supports full-page capture, element selection, device presets, custom headers and cookies, waits, caching, async jobs, and bulk capture; see the docs for parameter names and configuration. Learn about ScreenshotNeo, or sign up for 1,000 free screenshots a month with no card.

FAQ

Does --width guarantee a responsive mobile layout?

It sets the rendering width guideline, with strict handling available through --disable-smart-width. Page CSS and fixed-width content still determine how elements fit.

Should I use --height or --crop-h for a fixed image height?

Use --height for screen height and --crop-h to bound the output crop. Specify both when your capture needs both behaviors.

Is 800×600 a hard limit?

No general limit is established by the cited report. That value came from a historical, build-specific issue where reported screen resolution differed from requested viewport size.

Does the example command guarantee identical output on every platform?

No. The option meanings are documented, but output can vary with build, platform, and page. Check the installed binary’s help and inspect the result.