Can wkhtmltoimage Capture Pages Longer Than One Screen?

Yes. wkhtmltoimage can capture content longer than one screen. Its documented default calculates screen height from the page content, and --height lets you set that height explicitly. The manual does not specify a universal maximum or guarantee that every long-page layout will render completely, so inspect the output for your actual page. Debian wkhtmltoimage manpage.

1. Capture a page taller than the viewport

Start with the default behavior: specify a URL and an output file, without setting a fixed height.

wkhtmltoimage https://example.com long-page.png

When the content-calculated height works for your page, this is the simplest approach. Open the resulting image and confirm its bottom includes the content you need.

If you want to choose the screen height explicitly, set --height in pixels:

wkhtmltoimage --height 5000 https://example.com long-page.png

Replace 5000 with a height appropriate to the rendered page. There is no universal value: page length depends on the site, the selected width, and what the page renders.

2. Control width, height, and cropping

These options affect different parts of the result:

Option	What it controls	What to check
--width <int>	The screen width used for the capture. The manual describes width as a guide unless strict width is enabled.	A width change can alter text wrapping, which can change the page’s content height.
--height <int>	The screen height in pixels.	Make sure the chosen height extends past the content you want to include.
--crop-y <int>	A vertical crop position.	Check whether cropping is limiting the output you expect to be full-page.

For example, choose a width and height deliberately:

wkhtmltoimage --width 1280 --height 5000 https://example.com long-page.png

The width is not just a cosmetic choice. A narrower layout may wrap text onto more lines, making the document taller. Compare the output against the page at the same width.

3. Wait for JavaScript-rendered content

For pages that build content with JavaScript, wkhtmltoimage documents two readiness controls:

• --javascript-delay <msec> waits for a specified number of milliseconds.
• --window-status <windowStatus> waits for the page to expose a matching window status string.

Use a delay when you can estimate how long the page needs, or a status value when the page code can set a clear ready signal. For example:

wkhtmltoimage --javascript-delay 2000 https://example.com dynamic-page.png

A delay is a time-based wait, not proof that every script, image, or asynchronous request has finished. A status wait is useful only if the page actually sets the expected status. Verify the resulting image for content that arrives late.

4. Diagnose a short or incomplete capture

When the image stops early, identify whether the limit comes from the requested capture area, cropping, page rendering, or content that lives in a separate scrolling region.

Symptom	What to check	Next step
The output has roughly the height you specified.	Whether --height is set to a value shorter than the content.	Increase the height or try the content-calculated default, then inspect the image.
The output is cut off at a particular vertical point.	Whether --crop-y or another crop-related setting is in use.	Remove or adjust the crop option and capture again.
Text wraps differently and the page is taller than expected.	The selected --width and whether strict width is enabled.	Set the intended width deliberately and recalculate the height needed.
Content that appears after loading is missing.	Whether the page needs JavaScript time or an explicit ready signal.	Try --javascript-delay or --window-status, then check the output.
The main page is captured but a panel or feed is incomplete.	Whether that content is inside an element that scrolls independently.	Distinguish the document’s page height from the internal scroll region; the manual does not guarantee how every such layout will be captured.
Results differ between installations.	The installed wkhtmltoimage version and the page’s behavior in that build.	Record the version and reproduce with the target page. Historical project reports are version-specific and do not establish behavior for every build.

5. Version and reliability notes

Check the installed version when a timing or rendering issue is hard to reproduce:

wkhtmltoimage --version

Project issue #2142 recorded a failure report for version 0.12.2 and a fix milestone of 0.12.2.1. Issue #2217 is a separate report from a 0.12.2.1 user that was closed as invalid. These are historical reports about particular cases; they do not prove that current behavior is broken or fixed for every page and build. Issue #2142 · Issue #2217.

For reliable output, keep the capture width and timing settings consistent, retain representative output samples, and inspect long pages after changing the site or wkhtmltoimage version. The cited documentation does not establish an across-version maximum image dimension, so test the actual page rather than relying on a guessed universal limit.

6. Performance and cost considerations

A longer output contains more pixels than a viewport-sized image. Larger dimensions can mean more memory use, longer rendering or file handling, and larger output files; the exact impact depends on page content, image format, and environment. The research sources do not provide benchmarks or a maximum supported height. Use only as much height as the page requires, and consider whether one very tall image is practical for the downstream tool that will display or process it.

wkhtmltoimage is a command-line tool, so the capture cost is the compute and storage you provide for running it. There is no per-shot service charge for a local command, though your infrastructure still has costs.

7. Or skip the browser setup

If you need an API rather than a local browser capture, ScreenshotNeo takes a URL in one request and returns an image or PDF. Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An 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.

Install curl and replace the placeholder with your API key:

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

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js:

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

See the ScreenshotNeo API documentation for the request options. Sign up for 1,000 free screenshots a month with no card.

8. FAQ

Does wkhtmltoimage have a documented maximum page height?

The cited manpage describes the default content-calculated height and the --height option, but does not give a universal maximum.

Should I always set --height?

No. Try the default first. Set an explicit height when you need control over the capture area or the default does not include the intended content.

Does a delay guarantee that lazy or asynchronous content is ready?

No. It waits for a duration. Inspect the output, or use a page-controlled window status when the page can signal readiness.

Why does changing width affect how much content fits vertically?

Width changes line wrapping. More wrapped lines can make the rendered content taller.