Use a manually installed, Odoo-compatible wkhtmltox binary—not pip—to render an Odoo page or report as an image. For Odoo 10–15, Odoo’s compatibility guidance recommends wkhtmltox 0.12.5-1; for Odoo 16 and later, it recommends 0.12.6.1-3 on newer systems. Verify the binary as the Odoo service user, render a small local HTML file, then add the cookies, headers, JavaScript timing, dimensions and local-file permissions your report actually needs.
wkhtmltoimage is the headless HTML-to-image companion to wkhtmltopdf. It uses Qt WebKit and does not require X11, a desktop session or another display service. This guide covers Linux installation, Odoo asset and authentication issues, practical command options, containers, resource limits and a hosted alternative.
What wkhtmltoimage does in an Odoo deployment
The executable accepts an HTML file or URL and writes an image such as PNG, JPEG or WebP. Its documented command shape is:
wkhtmltoimage [OPTIONS]... <input file> <output file>Odoo normally produces HTML that references CSS, fonts, images and sometimes JavaScript-generated content. wkhtmltoimage requests those resources with its own Qt WebKit engine, lays out the page at a virtual viewport, and saves the result. Because it is headless, adding a virtual display is unnecessary.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
The renderer is separate from Odoo and is not a Python package. Odoo’s development setup explicitly says wkhtmltopdf is installed manually, not through pip; the same wkhtmltox package supplies wkhtmltoimage.
Choose a binary that matches your Odoo release
Do not select a package solely because its version is newest. Odoo’s maintained compatibility guidance distinguishes releases and warns that ordinary Debian or Ubuntu repository builds may lack the patched Qt features required for headers and footers.
| Odoo release | Recommended wkhtmltox build | Important qualification |
|---|---|---|
| 10 through 15 | 0.12.5-1 |
Use an Odoo-compatible patched-Qt build; distro packages may not provide the required features. |
| 16 and later | 0.12.6.1-3 |
This build enables --disable-local-file-access by default. |
These are operational recommendations, not a promise that one file works on every distribution. Record the Odoo major version, Linux distribution, CPU architecture and exact binary build when opening a support ticket. Recheck Odoo’s current compatibility page before upgrading an existing server.
Install wkhtmltoimage on Ubuntu or Debian
The following pattern mirrors Odoo’s documented Ubuntu/Focal setup. Replace the download URL and package name with the wkhtmltox artifact for your operating system, architecture and Odoo version. Do not blindly install an Ubuntu package on another distribution.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Download the matching wkhtmltox package. Obtain the vendor/Odoo-compatible
.debfor the required build. - Install a package helper and the file. For example, on a Debian-family host where
gdebiis available:sudo apt update sudo apt install -y gdebi-core sudo gdebi ./wkhtmltox_<version>_<architecture>.deb - Expose both executables on the standard path. Some packages install under
/usr/local/bin; Odoo’s example creates links into/usr/bin:sudo ln -sf /usr/local/bin/wkhtmltopdf /usr/bin/wkhtmltopdf sudo ln -sf /usr/local/bin/wkhtmltoimage /usr/bin/wkhtmltoimage - Verify as the Odoo account. A root shell can see a different PATH or file permission set:
sudo -u odoo command -v wkhtmltoimage sudo -u odoo wkhtmltoimage --versionThe first command should print the intended path; the second should show the expected build.
- Render a local smoke-test page before involving Odoo.
cat > /tmp/wkhtmltoimage-test.html <<'HTML' <!doctype html> <html><body><h1>wkhtmltoimage works</h1></body></html> HTML sudo -u odoo wkhtmltoimage --format png --width 800 --height 300 /tmp/wkhtmltoimage-test.html /tmp/wkhtmltoimage-test.png file /tmp/wkhtmltoimage-test.png
If the smoke test fails, fix PATH, execute permissions, shared libraries or package architecture before debugging Odoo templates.
Render an Odoo page or report
Render a public URL
wkhtmltoimage --format png --width 1200 --height 900
'https://example.com/your-odoo-route' odoo-page.pngUse a URL reachable from the machine running the command. “Reachable in my browser” is not sufficient when the server is inside a private network or container.
Rank #2
Render an exported HTML file
wkhtmltoimage --format webp --width 1400 --quality 90
/srv/odoo/export/report.html report.webpWith newer compatible binaries, local-file access is disabled by default. If the HTML references local CSS, fonts or images, either serve trusted assets over HTTP or explicitly allow only the directory required by that report. Avoid globally weakening the policy.
Pass authentication and request metadata
The Debian manual documents repeatable cookies and custom headers. Supply only credentials needed by the report endpoint, and protect shell history and process listings when values are sensitive.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemswkhtmltoimage --format png
--cookie session_id 'REDACTED_SESSION_VALUE'
--custom-header Authorization 'Bearer REDACTED_TOKEN'
'https://odoo.example.internal/report/image' report.pngAn apparently unstyled result often means the HTML loaded but its CSS, fonts or images were rejected as unauthenticated requests. Inspect each asset URL from the rendering host and provide the matching cookie or header.
Useful wkhtmltoimage options
| Need | Options | Example or guidance |
|---|---|---|
| Image type and compression | --format, --quality |
--format png preserves lossless output; JPEG/WebP quality values trade size for fidelity. |
| Viewport and framing | --width, --height, --crop-left, --crop-top, --crop-width, --crop-height |
Set dimensions deliberately instead of relying on defaults. |
| Scale | --zoom |
Increase or decrease layout scale when text or a fixed-width report is framed incorrectly. |
| Dynamic content | --javascript, --no-javascript, --run-script, --window-status |
Keep JavaScript enabled when Odoo populates content asynchronously; wait for an application status or run a short script. |
| Encoding | --encoding |
Set the page’s actual character encoding when non-ASCII text is corrupted. |
| Request identity | --cookie, --custom-header |
Repeat options for multiple cookies or headers required by the endpoint and its assets. |
A practical baseline is:
wkhtmltoimage --format png --width 1200 --quality 90 input.html output.pngMake asynchronous Odoo content appear
Qt WebKit can finish the initial HTML request before JavaScript has inserted charts, totals or images. First confirm that the content appears when JavaScript is enabled. Then choose a deterministic wait:
--window-status: have page JavaScript setwindow.statusafter rendering is complete, then wait for that value.--run-script: execute a small script that triggers a known action or waits for a condition. Keep it idempotent.- Application-side rendering: where possible, make the Odoo route return complete markup and avoid timing-dependent animation.
Do not solve a missing element by adding an arbitrary long delay first. Confirm network requests, JavaScript errors and the selector or status that signals readiness.
Diagnose blank images and missing CSS
1. Confirm the executable and patched Qt
Run command -v wkhtmltoimage and wkhtmltoimage --version as the Odoo service user. A distribution build can be found first and may lack Odoo’s required patched-Qt behavior.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Rank #3
2. Test the same URL from the rendering host
Check DNS, routing, TLS certificates, firewall rules and reverse-proxy access from the Odoo machine or container. A URL that works on a developer laptop may be private to that network.
3. Check authentication for every asset
HTML may be public while CSS, fonts, images or report endpoints require a session. Add the necessary cookie or custom header and verify that the response is the expected file rather than a login page.
4. Check JavaScript timing
Use --window-status or --run-script when content is inserted after load. Keep JavaScript enabled unless the page is known to be static.
5. Check dimensions and cropping
A page can be present but outside the visible frame. Set --width and --height, then adjust crop coordinates or --zoom. Compare a generous diagnostic viewport with the final dimensions.
6. Check local-file restrictions
For 0.12.6.1-3, local-file access is disabled by default. Prefer trusted HTTP asset URLs. If local assets are required, allow only the specific trusted directory using the relevant local-file option documented by your build.
7. Check output permissions and disk space
The Odoo account must be able to read the input and write the destination. Confirm the destination directory, free space and any container read-only filesystem policy.
Containers, services and security
Install the binary in the same image or host context as the Odoo worker that invokes it. Verify the executable and libraries inside the running container, not only on the host. Keep the binary path explicit in Odoo configuration when multiple versions are installed.
- Run rendering with a least-privilege service account.
- Do not place session cookies or bearer tokens in shared logs.
- Allow local files only from directories containing trusted report assets.
- Restrict outbound access if report URLs can be influenced by users; this reduces server-side request risks.
- Pin and document the package checksum and version so upgrades are reproducible.
Performance and large reports
Image dimensions, JavaScript, remote assets and network latency all affect completion time. Caching static assets, reducing unnecessary resources and using a fixed viewport make repeated captures more predictable. Avoid rendering an entire long report as one enormous image when separate pages or sections meet the requirement.
Odoo’s wiki warns that very large documents—its discussion uses 500-plus pages—can cause exponential memory and file-descriptor consumption. That is guidance rather than a benchmark. At that scale, split the work, reduce concurrency, raise appropriate service limits and monitor resident memory, open files, temporary storage and worker restarts.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. It removes cookie/consent banners, newsletter popups and chat widgets before capture; bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP tools—take_screenshot, get_page_info and capture_pdf—work with Claude, Cursor and other MCP clients.
For a one-call capture, 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.webpThe API also supports full-page and element captures, device or custom viewports, retina scale, dark mode, PDF settings, custom CSS and JavaScript, clicks, waits, blocked resources, headers, cookies, user agents, timezone, geolocation, transparent backgrounds, resizing, chosen-TTL caching, signed image links, asynchronous jobs, webhooks, bulk capture and a usage API. Those controls let you address many Odoo-like asset and timing cases without maintaining a Qt browser binary.
The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is on every plan. Create a free ScreenshotNeo account to get started.
Best Value
Equivalent calls from Python and Node.js
Python
Use this when your Odoo job already runs in Python. The request returns the image bytes; check the HTTP status before writing them.
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)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 failed: ${res.status}`);
const data = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', data));Operational checklist
- Odoo major version, operating system and architecture are recorded.
- The intended patched-Qt build is installed manually and resolved by the Odoo user.
wkhtmltoimage --versionmatches the documented choice.- A local HTML smoke test succeeds before Odoo testing.
- CSS, fonts and images are reachable with the required cookies or headers.
- JavaScript readiness is deterministic rather than an unexplained long delay.
- Viewport, crop, zoom, format and quality are explicit.
- Local-file access is limited to trusted assets.
- Large jobs are split or resource-limited and monitored.
Frequently Asked Questions
Can I install wkhtmltoimage with pip?
No. Odoo’s setup documentation treats wkhtmltox as a manually installed system binary; pip is not the installation path.
Why does the command work for root but fail in Odoo?
The service account may have a different PATH, permissions, libraries or access to the destination and asset directories. Verify the binary and smoke test as the Odoo user.
Free tools Windows power users keep installed
One-click scans. No signup required.
Should I use wkhtmltoimage or wkhtmltopdf?
Use wkhtmltoimage when the required output is an image. Both executables come from the wkhtmltox package, but their output and option sets differ.
What should I record before upgrading Odoo?
Record the Odoo major release, OS and architecture, wkhtmltox package name, binary version and local-file policy; then recheck Odoo’s current compatibility guidance.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
