The reliable fix is to make the rendering environment deterministic: use the same wkhtmltoimage binary and operating system in production, install and verify the required fonts with fontconfig, use a compatible local TTF or OTF for critical text, permit local-file access when necessary, wait for web fonts to finish loading, and define explicit fallbacks for every script you render. If glyphs are correct but spacing or edges still differ, Qt WebKit—not your CSS family name—may be the limiting factor.
Why wkhtmltoimage renders a different font
wkhtmltoimage is an open-source command-line renderer that converts HTML to images through the Qt WebKit engine. Its output depends on more than the CSS font-family declaration: the exact Qt/WebKit build, operating system, architecture, fontconfig database, FreeType library, font files visible to the process, and page-load timing all affect the result.
A family name is only a request. If that family is absent, cannot be parsed, or lacks a character, Qt chooses a substitute. The substitute may have different metrics, kerning, hinting, or glyph shapes. When no available font contains a character, the result is a missing-glyph box.
Use this diagnostic workflow
- Record the renderer. Run
wkhtmltoimage --versionand record the operating system, distribution, CPU architecture, and absolute path to the binary. Reproduce the problem with that same binary in production; Linux packages built with different Qt versions can render fonts differently. - Check fonts at the OS layer. Confirm that the family is installed for the user running the converter and that fontconfig can see it. Qt normally uses fontconfig for system-font access, with FreeType handling font rasterization. A font installed only in your desktop session may be invisible to a service account or container.
- Create a minimal test. Reduce the page to one heading and one paragraph. Render ASCII and the non-Latin text that fails. This separates a loading problem from missing glyph coverage and from raster-quality differences.
- Test a known local file. Use a local TTF or OTF that is known to contain the required characters. Give the element an explicit family stack rather than relying on a generic family.
- Verify webfont loading. Check URL resolution, file permissions, response content, MIME type, and whether the deployed format is supported by your Qt/FreeType combination. For local HTML and fonts, verify local-file permissions.
- Wait for late loading. If JavaScript injects CSS or a font after the initial page load, increase
--javascript-delayor coordinate capture with a page status value. Waiting cannot make an unsupported font format readable. - Inspect fallback directly. Assign the intended family to the exact element containing the affected script. Some 0.12-era builds do not perform reliable character-level fallback; separate script runs into different elements when necessary.
- Judge quality last. After glyph selection is correct, compare kerning, anti-aliasing, hinting, and edge sharpness. Those can remain different from a modern browser because they are renderer characteristics.
Confirm that the font is installed and visible
Linux
Install the font for the same account that runs wkhtmltoimage, refresh the distribution’s fontconfig cache, and query the family with your platform’s fontconfig tools. The important test is not whether the file exists somewhere on disk; it is whether the converter process can resolve the family and whether the file includes the glyphs you need.
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Containers and minimal servers commonly omit desktop fonts and fontconfig data. Copy only fonts whose licenses allow redistribution, install them during image creation, refresh the cache, and run a smoke test as the production user. Keep a deliberate fallback for symbols, accented text, and every writing system in your content.
Windows and macOS
Install the font system-wide or in the account that launches the process. Confirm that a service, scheduled task, or sandbox has access to the same font set as your interactive shell. Compare the absolute binary path and architecture as well as the font files; a different Qt build can change metrics even when the operating system is unchanged.
Make CSS fallback deliberate
Use a stack that reflects the scripts your page contains. Put the preferred family first, then families known to cover the required characters, and finish with a generic family:
body {
font-family: "Inter", "Noto Sans", Arial, sans-serif;
}
.cjk {
font-family: "Noto Sans CJK SC", "Microsoft YaHei", sans-serif;
}
.arabic {
font-family: "Noto Naskh Arabic", "DejaVu Sans", sans-serif;
}Do not assume one broad family covers every script. If the renderer’s fallback is unreliable, wrap script-specific text in separate elements as shown above. This also makes it easier to identify which family supplied a problematic glyph.
Fix local @font-face failures
Use a compatible, resolvable source
For a reproducible capture, bundle a licensed TTF or OTF and reference it with a URL that resolves from the HTML document:
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
@font-face {
font-family: "Report Sans";
src: url("fonts/report-sans-regular.ttf") format("truetype");
font-weight: 400;
font-style: normal;
font-display: block;
}
.report { font-family: "Report Sans", sans-serif; }Check capitalization, relative paths, permissions, and the file’s actual format. A browser accepting a modern webfont format does not prove that your deployed Qt WebKit and FreeType stack can parse it. Test the exact binary that creates the image.
Allow local files when the page is local
Local-file access can be blocked by the converter’s security settings. When your HTML and font are local files, run with the appropriate local-file option and restrict access to the directories you need. A typical command is:
wkhtmltoimage --enable-local-file-access input.html output.pngIf your build supports the settings API, the corresponding setting is commonly exposed as load.blockLocalFileAccess. Treat workarounds reported for one build—such as adding a hidden element that references the font—as experiments, not guarantees.
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 →Handle remote and Google web fonts
Remote fonts add DNS, TLS, network, caching, and timing variables. A page that looks correct in Chrome can fall back in wkhtmltoimage if the request fails or the capture starts first. Verify network access from the rendering host, inspect the font response, and compare the result with a bundled local copy. If the local copy works while the remote version does not, keep the local asset for production captures or fix the network path.
Use a delay only when the font is expected to arrive after page load:
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
wkhtmltoimage --javascript-delay 1500 https://example.com/page output.pngThe delay is in milliseconds and begins after the page-load phase. It cannot repair an unsupported format, a blocked request, or an incorrect URL. For pages you control, a JavaScript readiness flag or window-status value can provide a more deterministic hand-off than guessing a long delay.
Separate missing glyphs from visual-quality problems
Boxes, question marks, or one script missing
- The requested family is not installed or is invisible to fontconfig.
- The font file lacks the required Unicode range.
- The file could not be fetched, parsed, or read because of URL, permission, or local-access restrictions.
- The build does not perform the character-level fallback your page expects.
Render a minimal sample with the intended family assigned directly to the affected text. Then test a known coverage font. If the coverage font works, the issue is selection or glyph coverage rather than image encoding.
Correct letters, wrong spacing or kerning
Once the correct file and glyphs are confirmed, remaining differences can come from Qt WebKit’s text shaping and rasterization. Long-standing issue reports describe kerning differences and inconsistent results from -webkit-font-smoothing; CSS smoothing switches are not uniformly effective across platforms and builds. The wkhtmltopdf issue tracker documents these limitations at github.com/wkhtmltopdf/wkhtmltopdf/issues/45.
For pixel-sensitive work, compare the same binary, font files, viewport, device scale, and operating system. Do not treat a browser screenshot as a normative reference for a Qt WebKit image.
Capture commands that make testing repeatable
Minimal local test
wkhtmltoimage
--enable-local-file-access
--width 1200
--quality 95
test.html test.pngKeep the input, command line, binary version, and output together so a later change can be attributed to one variable.
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
Useful options while diagnosing fonts
| Option | Use | Important limitation |
|---|---|---|
--enable-local-file-access |
Permit local HTML, CSS, and font URLs. | Use only with files and directories you trust. |
--allow <directory> |
Whitelist a specific local directory. | Still requires paths that resolve correctly. |
--javascript-delay <ms> |
Wait for JavaScript-injected styles or fonts. | Does not add support for an unreadable format. |
--window-status <text> |
Capture after the page sets a readiness status. | The page must set the exact value. |
--debug-javascript |
Expose JavaScript errors during diagnosis. | It does not validate font responses. |
--encoding <name> |
Set the document character encoding when it is missing or wrong. | Encoding fixes misdecoded text, not absent glyphs. |
--width, --height, --zoom |
Keep geometry constant while comparing outputs. | Changing scale can make edges appear sharper or blurrier. |
Troubleshoot by symptom
“The family is declared but ignored”
Run the minimal test with a system-installed version of that family. If it still falls back, inspect fontconfig visibility, spelling, weight/style availability, and the process user. If the family is available only as a remote webfont, test a local TTF or OTF.
“The local webfont works in a browser but not here”
Check local-file access, URL resolution, permissions, MIME type, and format compatibility. Add a temporary delay to distinguish timing from parsing. If the local file remains unusable, choose a format supported by the deployed Qt/FreeType stack.
“Only production is wrong”
Compare wkhtmltoimage --version, binary path, OS image, architecture, installed fonts, fontconfig cache, and service user between development and production. Rebuild the production image with the same inputs and rerun the minimal fixture.
“Non-Latin characters are boxes”
Test a font with confirmed coverage, assign it directly to the affected span, and separate script runs into elements if character-level fallback fails. Also verify that the document encoding is correct.
“The font is right but the image is blurry”
Hold the font file and layout constant, then compare viewport and zoom settings. If glyph shapes are correct but anti-aliasing or kerning differs, you may be seeing a Qt WebKit limitation. Changing -webkit-font-smoothing is not a dependable fix.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
Reliability and performance practices
- Package the renderer and fonts together so upgrades are intentional.
- Run a startup smoke test containing Latin, symbols, and every non-Latin script your application emits.
- Prefer local fonts for regulated or high-volume rendering; remote requests add failure and latency paths.
- Use a readiness signal instead of an unnecessarily large fixed delay when you control the page.
- Cache font files at the image or host layer, but invalidate the cache when a font revision changes.
- Record the command, binary version, font checks, and output hash for reproducibility.
- Do not redistribute commercial fonts without the required license.
Or skip the browser setup
ScreenshotNeo provides a hosted screenshot API and MCP server when you do not want to maintain a Qt WebKit/fontconfig stack. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. Its MCP tools—take_screenshot, get_page_info, and capture_pdf—work with Claude, Cursor, and other MCP clients.
One GET request returns PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for all options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo includes full-page and element capture, lazy-image loading, dark mode, device presets and custom viewports, retina scale, PDF controls, HTML/CSS-to-image, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed links, asynchronous webhooks, bulk capture for up to 100 URLs per call, usage data, and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work.
The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 screenshots; yearly billing provides two months free, and every feature is available on every plan. Create a free ScreenshotNeo account to start.
Recommended Free Tools
Frequently Asked Questions
Can I make wkhtmltoimage use a browser-installed font without installing it on the server?
No. The converter can use only fonts visible to the process through its operating system and fontconfig/FreeType stack, or fonts it can successfully load from the page.
Does converting the font to WOFF2 guarantee that wkhtmltoimage will load it?
No. Compatibility depends on the deployed Qt WebKit and FreeType versions. Validate the exact binary; a local TTF or OTF is often the more predictable test format.
Why does changing the output from PNG to JPEG not fix text rendering?
Image format affects compression and color representation after rendering. It does not change font selection, glyph coverage, shaping, or Qt’s anti-aliasing.
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.
