To use wkhtmltoimage with Odoo, install a manually downloaded, Odoo-compatible wkhtmltox package, verify that the Odoo service user can execute the intended binary, then render a small local HTML file before troubleshooting Odoo assets. Odoo’s compatibility guidance lists 0.12.5-1 for Odoo 10–15 and 0.12.6.1-3 for Odoo 16 and newer systems; confirm the current recommendation for your operating system and architecture before deploying.
What wkhtmltoimage does in an Odoo deployment
wkhtmltoimage is the image-rendering companion to wkhtmltopdf. The Odoo-maintained fork describes both as command-line tools that render HTML with the Qt WebKit engine. They run headlessly, so an X display or display service is not required. Odoo uses the same browser engine for report-related rendering, but an image workflow still depends on the binary being installed and reachable by the Odoo process.
The executable accepts a local HTML file or URL and writes an image in a selected format. It is not installed through pip. Odoo’s development setup says to install the appropriate package manually, particularly when patched-Qt features such as headers and footers are needed.
Choose the binary that matches your Odoo release
| Odoo release | Odoo compatibility recommendation | Important qualification |
|---|---|---|
| 10–15 | 0.12.5-1 |
Use the Odoo-compatible build, not an arbitrary distribution package. |
| 16 and later | 0.12.6.1-3 |
Newer systems may enable --disable-local-file-access by default. |
These are version-specific operational recommendations, not a promise that every operating-system package will behave identically. Record the Odoo major version, OS distribution, CPU architecture, package filename, and the output of wkhtmltoimage --version when opening a support case. Debian and Ubuntu repository builds can lack the patched Qt required for Odoo’s headers and footers, so a package that merely starts may still be unsuitable.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Install wkhtmltoimage on Ubuntu or Debian
The following flow mirrors Odoo’s documented Ubuntu/Focal example. Replace the download URL and package name with the build matching your host and Odoo release; do not blindly reuse a Focal package on another distribution.
- Install a package helper if your image does not already include one:
sudo apt update sudo apt install -y gdebi-core - Download the matching
wkhtmltox.debfrom the Odoo-compatible release you selected:cd /tmp wget https://example.invalid/wkhtmltox_<matching-build>.debThe placeholder above is intentional: select the real package for your OS and architecture from Odoo’s compatibility guidance rather than guessing a URL.
- Install it and resolve dependencies:
sudo gdebi /tmp/wkhtmltox_<matching-build>.deb - Make both commands discoverable in the conventional locations used by Odoo setups:
sudo ln -sf /usr/local/bin/wkhtmltopdf /usr/bin/wkhtmltopdf sudo ln -sf /usr/local/bin/wkhtmltoimage /usr/bin/wkhtmltoimage - Verify the path and build as the same account that runs Odoo:
command -v wkhtmltoimage wkhtmltoimage --version sudo -u odoo command -v wkhtmltoimage sudo -u odoo wkhtmltoimage --version
If your installation places the binaries somewhere else, fix the service account’s PATH or configure Odoo to use the correct executable location. A shell test as your personal account does not prove that a systemd service, container, or supervisor process can find the binary.
Prove the renderer works before involving Odoo
Create a deliberately small page with no external dependencies:
Rank #2
cat > /tmp/wkhtml-test.html <<'EOF'
<!doctype html>
<html><body><h1>wkhtmltoimage test</h1><p>Renderer is running.</p></body></html>
EOF
wkhtmltoimage --format png --width 1200 --quality 90
file:///tmp/wkhtml-test.html /tmp/wkhtml-test.png
file /tmp/wkhtml-test.pngOpen the resulting file or inspect it with an image tool. If this fails, resolve the binary, permissions, shared-library, or package problem before investigating Odoo templates.
Render an Odoo page or report endpoint
The basic command shape is:
wkhtmltoimage [OPTIONS]... <input file or URL> <output file>A practical local example is:
wkhtmltoimage --format png --width 1200 --quality 90
http://127.0.0.1:8069/my/endpoint /tmp/odoo-page.pngThe URL must be reachable from the machine running the command. For a protected Odoo endpoint, pass only the cookies and headers required by that endpoint:
wkhtmltoimage --format png --width 1200
--cookie session_id YOUR_SESSION_VALUE
--custom-header Authorization 'Bearer YOUR_TOKEN'
https://odoo.example.com/report/image/123 /tmp/report.pngDo not put real session values in shell history or shared process listings. Prefer a restricted environment, short-lived credentials, and a service account with the minimum access needed.
Options that matter for Odoo images
Output and framing
--format png|jpg|webpselects the output type supported by your build.--quality 90controls lossy output quality where applicable.--widthand--heightdefine the viewport. Set them deliberately instead of relying on defaults.--crop-x,--crop-y,--crop-w, and--crop-htrim the rendered area.--zoomchanges effective page scale when CSS pixels and the desired image size do not line up.
Authentication and request behavior
--cookie name valuerepeats a cookie for the page and its requests.--custom-header name valuesupplies request headers required by an authenticated endpoint.--encodingsets the page character encoding when it is not detected correctly.
JavaScript and asynchronous pages
- Keep JavaScript enabled when Odoo or a custom widget populates the page in the browser.
--window-status valuewaits for the page to set a matching status before capture.--run-script '…'runs a script before capture. Use it only with trusted content and keep it deterministic.- Disable JavaScript only when you know the page is entirely server-rendered; otherwise the output may be empty or incomplete.
Local files and security
For the 0.12.6.1-3 line, Odoo’s notes say --disable-local-file-access is enabled by default. This prevents a page from reading arbitrary local paths, but it can also block legitimate CSS, fonts, or images stored on disk. Allow access only to a trusted directory when the report requires it, and do not remove the restriction broadly on untrusted URLs.
Rank #3
Why an Odoo image is blank or missing CSS
The wrong executable is running
Run command -v and --version as the Odoo service user. Distribution builds may lack patched Qt features even though they render a simple page.
Assets cannot be reached
Inspect the generated HTML and test every CSS, font, and image URL from the renderer host. An Odoo page that looks correct in your browser can be unstyled when its asset requests require a session cookie, private DNS, a proxy, or a custom header.
JavaScript has not finished
Use a deterministic readiness signal such as --window-status, or a narrowly scoped --run-script. A fixed delay can help, but it is less reliable when network or server time varies.
Viewport dimensions are wrong
Responsive CSS can hide content at a narrow default width. Set --width and --height, then use crop or zoom to obtain the required framing.
Local-file access is blocked
With newer compatible binaries, inspect whether the default local-file policy is rejecting a stylesheet or image. Permit only the specific trusted asset directory rather than enabling unrestricted file access.
The job is too large
The Odoo wiki warns that very large documents—its discussion uses 500 or more pages—can cause exponential memory and file-descriptor usage. Split the work, reduce the report size, or raise appropriate service limits after measuring the host’s capacity.
Container and service deployment checks
- Install the binary inside the container or VM that actually performs the render; installing it on the host does not make it available in a container.
- Pin the package and record its checksum or image version so workers do not run different Qt builds.
- Ensure the service user can read templates, fonts, and permitted local assets.
- Confirm outbound DNS, proxy, and firewall rules for every remote asset domain.
- Set timeouts and concurrency conservatively. A burst of large renders can exhaust memory even when one command succeeds.
- Log the command version, target URL, dimensions, exit status, and elapsed time, while redacting cookies and authorization values.
Or skip the browser setup
If you need a clean screenshot rather than an Odoo-local renderer, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. It also offers an MCP server for Claude, Cursor, and other MCP clients with take_screenshot, get_page_info, and capture_pdf.
See the ScreenshotNeo API documentation for all options, including viewport and device presets, full-page and selector capture, dark mode, retina scale, custom CSS or JavaScript, waits, request blocking, cookies, headers, geolocation, PDFs, caching, signed links, asynchronous jobs, bulk capture, and usage reporting.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →cURL
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://your-odoo.example.com
-o shot.webpPython
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://your-odoo.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://your-odoo.example.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
require('fs').writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));The Free plan includes 1,000 shots each 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 an access key.
Best Value
FAQ
Does wkhtmltoimage need a graphical desktop?
No. The Odoo-maintained tools run headlessly and do not require a display service.
Can I install it with pip?
No. Install a compatible wkhtmltox package manually and expose the executable to the Odoo service.
Should I use the newest upstream release?
Not automatically. Match the Odoo major version and the Odoo compatibility guidance, then verify the actual binary build on the host.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWhy does a browser show the page correctly but wkhtmltoimage does not?
The renderer may lack the browser’s cookies, headers, reachable asset paths, JavaScript wait condition, viewport width, or permission to read local files.
Frequently Asked Questions
Can wkhtmltoimage render an authenticated Odoo page?
Yes, when the endpoint accepts the supplied session cookies or headers; pass only the credentials required and keep them out of shared logs.
Which format is best for an Odoo report image?
PNG is usually appropriate for text and UI screenshots; use JPEG or WebP when smaller lossy files are acceptable.
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.
