How to Set the Output Width and Height in wkhtmltoimage

Use --width and --height to set wkhtmltoimage’s screen dimensions. Width is a guideline by default; add --disable-smart-width when the requested width must be strict. If you need a bounded output rectangle, set crop dimensions separately with --crop-w and --crop-h.

For example, render an HTML file with a 1200 by 800 screen and strict width:

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

The screen dimensions influence page layout. Crop options select bounds from the rendered image; they do not set the layout viewport. Exact results can vary with the installed build and page content, so inspect the output for overflow or clipping.

1. Set the screen width and height

Pass integer pixel values to the corresponding options:

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

--width sets the screen width used to render the page. The documented behavior treats it as a guideline unless smart width is disabled. --height sets the screen height; when omitted, the height is calculated from page content. This means that setting a height does not crop the output to that height. Use crop options if you need a fixed rectangular selection.

2. Make the width strict when needed

When the layout must use the requested width even if content does not fit, add --disable-smart-width:

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

A strict width can cause wide content to overflow or be clipped. Check the rendered image and adjust the page or dimensions if necessary. The option descriptions are documented in the Ubuntu wkhtmltoimage manual; Debian’s source also registers the smart-width and dimension flags for its packaged build.

3. Set crop bounds separately

For a 1200 by 800 crop, specify crop width and height in addition to the screen dimensions:

wkhtmltoimage --width 1200 --height 800 --disable-smart-width \
  --crop-w 1200 --crop-h 800 input.html output.png

To move the crop origin, provide --crop-x and --crop-y as well:

wkhtmltoimage --width 1600 --height 1000 --disable-smart-width \
  --crop-x 100 --crop-y 50 --crop-w 1200 --crop-h 800 \
  input.html output.png

Use screen width and height to control rendering dimensions, then crop flags to choose the image bounds. A crop can exclude content outside its rectangle; inspect the result whenever you change its size or origin.

4. Choose the right dimensions for your task

Need	Options	What to check
Set the screen width used for layout	--width N	Width may be treated as a guideline.
Keep the requested width strict	--width N --disable-smart-width	Content wider than the screen may overflow or be clipped.
Set screen height	--height N	Height alone does not define a crop rectangle.
Select crop dimensions	--crop-w N --crop-h N	Content beyond the crop bounds is excluded.
Position the crop	--crop-x N --crop-y N	Confirm the crop starts at the intended location.

5. Common sizing problems

The output is wider than the requested width

Cause: --width is documented as a guideline by default.
Fix: add --disable-smart-width, then check whether any page content extends beyond the strict width.

The output height does not match the requested height

Cause: screen height and crop height are separate settings; without --height, the height is calculated from page content.
Fix: set --height for the screen and use --crop-h when you need a defined crop height.

Content is missing at the edge

Cause: a strict screen width or crop rectangle can exclude content that does not fit.
Fix: inspect the layout and crop origin, increase the relevant dimensions, or adjust the page content before capturing.

Flags appear to behave differently across machines

Cause: installed package builds may differ. The Ubuntu Noble manual describes packaged version 0.12.6-2build2, while the cited Debian source is version 0.12.6-2.
Fix: check the installed wkhtmltoimage version and consult documentation for that build. Validate the output on the environment where the command will run.

6. Reliability, performance, and cost notes

The documented sizing options specify dimensions and crop behavior; they do not provide a performance benchmark or guarantee identical results for every page and build. A strict width or smaller crop may omit content, so include output inspection in workflows where dimensions matter. This command-line method has no service pricing component; operating costs depend on the machine and workflow running it.

Or skip the browser setup

For a hosted capture, ScreenshotNeo accepts a URL and returns an image or PDF. The API can set viewport dimensions and includes full-page capture, device presets, retina scale, and other capture options. 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

Or make the same request in Python:

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)

And in Node.js:

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

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Sign up for ScreenshotNeo’s free plan.

FAQ

Does --height crop the page?

No. It sets screen height. Use --crop-h to set crop height.

Do I always need --disable-smart-width?

No. Add it when the requested width must be strict; otherwise width is a guideline by default.

Can I set crop position without changing screen dimensions?

Yes. Set --crop-x and --crop-y independently of screen width and height.

References

• Ubuntu Noble wkhtmltoimage manual
• Debian wkhtmltoimage source, version 0.12.6-2