How to Make wkhtmltoimage Screenshots Smaller Without Losing Readability
Reduce wkhtmltoimage file sizes by tuning JPEG quality, capture dimensions, and crop settings—then check legibility at the size people will actually view.
To make a wkhtmltoimage screenshot smaller without making it hard to read, first remove pixels you do not need by choosing an appropriate capture width or crop. If the page contains photographs or mixed content, save as JPEG and lower --quality gradually, checking text and edges at the screenshot’s intended display size after each change. For text-heavy pages, diagrams, and sharp edges, compare PNG with JPEG. There is no universal quality or width setting that guarantees readable results for every page.
The examples below use the wkhtmltoimage command line. Option availability can vary by build or wrapper; check the installed binary with wkhtmltoimage --version and wkhtmltoimage --extended-help.
1. Start with a baseline
Save a screenshot using the settings you use today. Record its byte size and inspect it at the size where it will actually be shown. Look for small text, thin lines, chart labels, and artifacts around sharp edges. This gives you a reference for deciding whether each change is acceptable.
wkhtmltoimage input.html baseline.png
For a URL instead of a local HTML file, pass the URL as the input:
wkhtmltoimage https://example.com baseline.png
Use representative pages in your comparison: a text-heavy page, a page with photographs, and any page with charts or small controls. A setting that works for one layout may not work for another.
2. Choose a format that suits the page
The documented image formats are JPG, PNG, BMP, and SVG. JPEG has a --quality control; the documentation does not publish a format-by-format size or readability benchmark.
| Format | When to compare it | What to inspect |
|---|---|---|
| JPG/JPEG | Photographs or mixed pages where a smaller compressed image is useful | Text clarity, halos or blocks around letters, and detail in photos |
| PNG | Text-heavy interfaces, diagrams, and sharp edges | Whether the result is acceptably sized and keeps fine details clear |
| BMP | When a workflow specifically needs this format | Whether its output size fits the use case |
| SVG | When a vector output is suitable for the page and downstream workflow | Whether the output works as expected in the target viewer |
Do not assume changing extensions converts the image. Choose an output format supported by your installed build and verify the resulting file with the tools in your workflow.
3. Tune JPEG quality in small steps
The --quality option controls JPEG compression and accepts values from 0 to 100 in the cited documentation. Lower values are candidates for smaller JPEGs, but the option is not a readability guarantee. Try a few nearby values and inspect each result at its final viewing size.
wkhtmltoimage --width 1200 --quality 85 input.html screenshot.jpg
1200 and 85 are example starting values, not universal recommendations. For an existing JPEG workflow, vary one setting at a time so you can see what changed:
wkhtmltoimage --quality 90 input.html quality-90.jpg
wkhtmltoimage --quality 80 input.html quality-80.jpg
wkhtmltoimage --quality 70 input.html quality-70.jpg
Compare both file size and visible quality. Stop lowering quality when text, line work, or important image detail becomes difficult to distinguish. If lower-quality JPEGs make text look rough, compare a PNG output instead of continuing to reduce JPEG quality.
4. Reduce unnecessary pixels with width and crop settings
--width sets the rendering screen width. By default it is a guide; --disable-smart-width makes the specified width strict. A strict width can leave content outside the specified area, so inspect for overflow or clipping before using it in production.
wkhtmltoimage --width 1200 input.html screenshot.png
wkhtmltoimage --width 1200 --disable-smart-width input.html strict-width.png
Use the first command when you want to guide the render width. Try the second only if you need the requested width enforced, and verify that the page still fits. A narrower viewport can trigger a different responsive layout, so confirm that the captured version still contains the content you need.
If only part of the rendered page matters, crop to that region instead of keeping large empty margins or unrelated page areas. The documented crop controls include width, height, and crop coordinates. Check your binary’s extended help for the exact option names and syntax available in your build:
wkhtmltoimage --extended-help
After cropping, inspect all four edges for cut-off labels, shadows, or content. A crop reduces captured area; it does not make text within that area more readable.
5. Treat zoom and JavaScript timing as rendering choices
A zoom factor is available, but the documentation does not give a universally optimal value for reducing file size. Zoom changes the rendered scale and composition, so check readability, layout, and clipping together if you adjust it. Do not use zoom as a substitute for choosing an appropriate output format or JPEG quality.
The library settings document a JavaScript delay after page load. Set a delay only when the page needs time to show the state you want to capture, such as content created after load. The delay affects capture timing, not image compression. Confirm the option syntax supported by your installed command or wrapper.
6. Compare outputs systematically
- Pick representative pages and capture a baseline.
- Try a suitable format, then test a few JPEG quality values if using JPEG.
- Try a narrower rendering width or a crop only if the removed pixels are genuinely unnecessary.
- Change one setting at a time and note the file size in bytes.
- Inspect the image at its intended display size, checking small text, edges, completeness, and any needed transparency or vector behavior.
- Keep the smallest output that remains legible and complete for the intended use.
This is a comparison workflow, not a benchmark: page content, build, and display size all affect the result.
7. Troubleshooting
| Symptom | Likely cause | What to try |
|---|---|---|
| The JPEG is still too large | The page has substantial image detail, or quality is still high for this use | Test lower --quality values gradually. Also remove unused page area with width or crop settings where safe. |
| Text looks rough or smeared | JPEG compression is damaging fine text and edges | Raise JPEG quality or compare PNG. Judge at the actual viewing size. |
| Content is cut off | A strict width or crop excludes part of the page | Increase the width or crop bounds, remove --disable-smart-width, or use a wider responsive layout. |
| The output width differs from the requested width | --width is a guide unless smart width is disabled |
Try --disable-smart-width and check for overflow or clipping. |
| The captured page is missing dynamic content | The page did not reach the desired state before capture | Use an appropriate JavaScript delay supported by the installed build, then check the resulting capture. Delay does not compress the output. |
| An option is rejected | The installed build or wrapper may not expose the same options | Check wkhtmltoimage --version and wkhtmltoimage --extended-help; use the syntax listed by that binary. |
| Changing the extension does not change the format | The output format is selected or inferred differently by the build | Use a supported output format and verify the resulting file rather than relying on the filename alone. |
8. Performance, reliability, and cost considerations
For a local command-line workflow, reducing output dimensions or captured area reduces the amount of image content being produced. JPEG quality is a compression control, but the cited documentation does not quantify file-size savings or processing speed for particular settings. Measure output sizes on your own representative pages instead of planning around an assumed percentage.
For reliable results, keep a small set of representative pages and inspect captures after changing format, width, crop, or zoom. Dynamic pages may need an appropriate JavaScript delay to reach the desired state. Builds and wrappers can differ, so verify option support against the installed binary.
wkhtmltoimage is a local rendering tool; the cited option documentation does not specify a service price. If you use a hosted screenshot API instead, include its plan and request costs in your workflow decision.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. It accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup 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 gives AI agents tools for screenshots, page information, and PDF capture.
Example cURL request for a WebP screenshot:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
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)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}`);See the ScreenshotNeo API documentation for request options. Plans include 1,000 screenshots a month free with no card, then $5 for 3,000, $15 for 15,000, $39 for 60,000, $99 for 250,000, and $249 for 1,000,000; yearly billing gives two months free. Every feature is on every plan. Sign up for 1,000 free screenshots a month with no card.
FAQ
Is quality 85 the recommended setting?
No. It is an example starting point. Compare settings on your pages and inspect the result at the intended display size.
Will PNG always be smaller for text?
The cited documentation does not establish a size winner. Compare PNG and JPEG for your page and judge both file size and legibility.
Does a smaller viewport guarantee a smaller screenshot file?
It can reduce captured pixels, but responsive layout changes and clipping can affect the result. Inspect the output rather than assuming a particular size reduction.
Does waiting longer make the image smaller?
No. A JavaScript delay gives a page more time to render dynamic content; it is not documented as a compression control.
