ScreenshotNeo

BlogHow-to

How to Fix python-imgkit Failing to Render the Whole Page

Fix partial python-imgkit screenshots by checking crop settings, viewport width, JavaScript timing, renderer errors, and headless display setup.

By the ScreenshotNeo team30 September 20268 min read

How to Fix python-imgkit Failing to Render the Whole Page

If imgkit produces only a small part of a page, the Python wrapper is rarely the only thing involved. imgkit delegates rendering to wkhtmltoimage, so the final image depends on wrapper options, renderer width, JavaScript timing, the page’s layout, and the environment running the binary.

Start with this order: remove unintended crop options, verify the viewport width, wait for dynamic content, run the generated renderer command directly, and check the headless display configuration. The sections below show how to isolate each cause with runnable examples.

1. Confirm what is actually rendering

Before changing options, save the exact input and record the renderer version. A reproducible case should include:

  • The source URL or HTML file.
  • Your complete imgkit options dictionary.
  • The operating system and Python version.
  • The output format and destination path.
  • The result of wkhtmltoimage --version.
python -m pip show imgkit
wkhtmltoimage --version
python --version

imgkit is a wrapper; it does not replace the renderer. The package documentation also recommends executing the underlying command shown in an exception so you can see diagnostics that are hidden when everything is called through Python. See the imgkit documentation for wrapper behavior and option handling.

2. Remove accidental crop settings

The most common explanation for a “small part of the page” is an option that explicitly restricts the output. wkhtmltoimage supports crop width, crop height, and crop coordinates. In imgkit, those options use hyphenated names such as crop-w, crop-h, crop-x, and crop-y.

A screenshot result depends on crop settings, viewport layout, and when the page finishes loading.
A screenshot result depends on crop settings, viewport layout, and when the page finishes loading.

First, capture with a minimal configuration:

import imgkit

imgkit.from_url(
    "https://example.com",
    "page.png",
    options={"format": "png"},
)

If this output contains the complete page, add your previous options back one at a time. Remove any crop setting that you did not intentionally choose:

options = {
    "format": "png",
    # Do not set these unless you want a fixed region:
    # "crop-w": 800,
    # "crop-h": 600,
    # "crop-x": 0,
    # "crop-y": 0,
}
imgkit.from_url("https://example.com", "page.png", options=options)

A crop height is different from a full-page capture. It tells the renderer how much of the rendered surface to copy. If the page is taller than that value, the lower content will never reach the output.

3. Set and verify the viewport width

Responsive pages can have entirely different layouts at different widths. A navigation bar may collapse, columns may stack, and JavaScript may choose a different component tree. The renderer’s --width value is a layout input. With smart width enabled, it acts as a guide; with --disable-smart-width, it becomes strict.

Try an explicit width that matches the layout you expect:

import imgkit

options = {
    "format": "png",
    "width": 1440,
}
imgkit.from_url("https://example.com", "desktop.png", options=options)

If you need a strict viewport, compare the result with smart width disabled:

options = {
    "format": "png",
    "width": 1440,
    "disable-smart-width": "",
}
imgkit.from_url("https://example.com", "strict-width.png", options=options)

Use the same width when comparing runs. Otherwise a “missing” section may simply have moved below a responsive breakpoint. Inspect the page in a normal browser at the target width and compare its layout with the rendered image.

4. Wait for JavaScript and lazy content

Many pages are only shells at initial load. JavaScript then fetches data, inserts components, draws charts, or loads images. If capture starts immediately, the screenshot can contain the header and an empty content area.

A fixed delay is the simplest solution:

import imgkit

options = {
    "format": "png",
    "javascript-delay": 1000,
}
imgkit.from_url("https://example.com/app", "after-delay.png", options=options)

The delay is in milliseconds. Increase it only as much as needed; a large value raises latency for every request. A more deterministic approach is to coordinate the page with window.status. The page sets a known status after its data and layout are ready, and the renderer waits for that value:

import imgkit

options = {
    "format": "png",
    "window-status": "screenshot-ready",
}
imgkit.from_url("https://example.com/app", "status-gated.png", options=options)

For a page you control, set the status after the final render step:

<script>
  loadDashboard().then(() => {
    renderCharts();
    window.status = "screenshot-ready";
  });
</script>

If the page never sets that value, the capture can wait indefinitely or fail according to the renderer’s behavior. Test the ready path in a browser first, and use a delay when you cannot change the page.

5. Run the renderer command directly

When imgkit raises an exception, copy the generated wkhtmltoimage command from the error and run it in a shell. This separates Python configuration errors from renderer failures, missing libraries, network problems, and crashes.

wkhtmltoimage \
  --format png \
  --width 1440 \
  --javascript-delay 1000 \
  https://example.com \
  direct.png

Look for messages about an unavailable protocol, SSL, blocked resources, JavaScript errors, or a process crash. Some wkhtmltoimage versions are documented as capable of segmentation faults. If the direct command crashes with the same input, changing Python code will not repair it; try a supported renderer build and reduce the page to a minimal reproduction.

6. Fix headless server display issues

On a desktop, the renderer can use the local display. On a headless Linux server, container, or CI worker, display setup can be the failure point. The imgkit documentation describes using Xvfb and passing the xvfb option or configuring its executable path.

import imgkit

config = imgkit.config(
    xvfb="/usr/bin/xvfb-run"
)
imgkit.from_url(
    "https://example.com",
    "headless.png",
    config=config,
    options={"format": "png"},
)

The executable path differs by distribution. Confirm it with command -v xvfb-run. If your deployment already starts Xvfb, do not start a second display blindly; instead pass the correct display environment to the process.

7. A complete diagnostic script

This script captures a URL with a controlled width, waits for JavaScript, and logs the configuration. Remove the delay or replace it with window-status when the page provides a ready signal.

from pathlib import Path
import imgkit

URL = "https://example.com"
OUTPUT = Path("diagnostic.png")

options = {
    "format": "png",
    "width": 1440,
    "javascript-delay": 1000,
    # Keep crop options out until the full page works.
}

print("URL:", URL)
print("Output:", OUTPUT.resolve())
print("Options:", options)
imgkit.from_url(URL, str(OUTPUT), options=options)
print("Wrote", OUTPUT.stat().st_size, "bytes")

8. Troubleshooting checklist

Symptom Likely cause Fix
Only a fixed rectangle appears crop-w or crop-h is set Remove crop dimensions and coordinates, then retry.
Desktop content is missing or stacked Viewport width differs from the expected breakpoint Set width; compare smart and strict width.
Header appears but data does not Capture starts before JavaScript finishes Use javascript-delay or a window-status signal.
Command exits with a crash Renderer version or page triggers a wkhtmltoimage failure Run the command directly, record the version, and test a different supported build.
Works locally but fails in CI No display server or missing shared libraries Configure Xvfb and verify executable paths.
Images are blank or absent Lazy loading, blocked resources, or capture before image requests finish Wait longer, trigger loading in page code, and inspect direct-command diagnostics.
Page height varies between runs Asynchronous content or fonts change layout Use a readiness signal and make external dependencies deterministic.
ScreenshotNeo removes common consent banners, popups, and chat widgets before capture.
ScreenshotNeo removes common consent banners, popups, and chat widgets before capture.

9. Performance, reliability, and cost considerations

Performance

Rendering cost grows with page complexity, resource count, JavaScript execution, and wait time. Start with one URL and a small delay, then measure the command duration. Avoid an unnecessarily large viewport and avoid waiting several seconds when a readiness signal is available. Full-page pages with many images can consume more memory than a fixed crop.

Reliability

Pin the renderer version in deployment, keep a known-good test URL, and save failed inputs with their options. Treat remote resources as unreliable: a third-party script, font, or API can change the final height or prevent a ready signal. A timeout around the Python process prevents one page from holding a worker forever. Retry only transient failures; repeated retries will not fix a deterministic crop or width mismatch.

Cost

Self-hosting avoids a per-shot service charge but shifts work to your own machines, browser dependencies, monitoring, and maintenance. If you capture at scale, account for CPU, memory, queueing, and failed jobs when choosing worker limits.

Or skip the browser setup

If you need reliable screenshots without installing and maintaining wkhtmltoimage, ScreenshotNeo provides a GET endpoint that returns PNG, JPEG, WebP, or PDF. The API handles the browser environment and exposes capture controls for full-page output, selectors, waits, custom CSS and JavaScript, headers, cookies, user agents, blocking rules, device presets, and more. See the ScreenshotNeo API documentation for the complete option list.

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,
)
r.raise_for_status()
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}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. ScreenshotNeo also has an MCP server so Claude, Cursor, and other MCP clients can call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Does imgkit have a single full-page flag?

No. Full output depends on the renderer surface, crop settings, viewport, and when the page is captured. Remove crop limits and make loading deterministic.

Should I always disable smart width?

No. Compare both modes. Smart width can fit content naturally; strict width is useful when you need a repeatable responsive layout.

Is a reported Folium failure proof that Folium is incompatible?

No. A report of a Folium map rendering only a small part is an input-specific symptom. Check crop settings, width, JavaScript timing, and renderer diagnostics before blaming the page framework.

Why does a delay fix one page but not another?

A delay only waits a fixed amount. Pages with variable network or data time need a readiness signal, such as window.status, or page code that makes all required content available before capture.

What should I attach when asking for help?

Include the HTML or URL, options, generated command, operating system, wkhtmltoimage --version, and the smallest output that still reproduces the problem.