If wkhtmltopdf shows boxes, substitutes a typeface, or omits a web font, first find out whether the problem is missing glyphs, fontconfig visibility, an inaccessible font file, or a difference in the binary or runtime. Diagnose it on the same machine, under the same account and environment that generates the PDF. UTF-8 settings can fix text decoding; they cannot install a font or add glyphs to one.
Start by identifying what is failing
Before changing CSS or installing packages, reproduce the problem with a small HTML file and capture the environment that runs the converter. A font that works in a desktop browser may not be installed or reachable by wkhtmltopdf on a server, inside a container, or under a service account.
As an Amazon Associate I earn from qualifying purchases.
- Run
wkhtmltopdf --versionand record its full output. - Record the operating system and version, architecture, installation package or binary, and whether the process runs as a service, in a container, or in a serverless function.
- Make a minimal HTML example containing the relevant
font-family, any@font-facerule, and sample text with the affected characters. - Generate the PDF in the same runtime context as production. A successful test in an interactive shell does not establish that a service process has the same environment or file access.
The wkhtmltopdf project asks bug reports to include the version, operating system and version, and a detailed test case with HTML, CSS, and JavaScript. See its issue tracker for that reporting context.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsDistinguish encoding errors from missing glyphs
If the PDF contains malformed byte sequences or question marks, investigate how the HTML is decoded: check its character encoding and, if the content is fetched remotely, the response headers. The web.defaultEncoding setting is documented as a way to guess an encoding when content does not specify it properly; it does not provide font coverage. See the wkhtmltopdf settings reference.
#1 Best Overall
If the text is decoded but appears as boxes or fallback characters, check whether the selected font contains the required glyphs and whether the renderer can see and use that font. A wkhtmltopdf issue about Chinese text records one user’s report that installing a Chinese font package resolved the problem, despite attempts to set UTF-8. That report is a diagnostic clue, not a universal package recommendation: the right font depends on the script and distribution. See the Chinese-character issue.
Check fontconfig and installed fonts on Linux
wkhtmltopdf relies on system-installed fonts and the fontconfig and freetype2 runtime configuration. Check those dependencies where the process actually runs, not only on a developer workstation. The project describes these dependencies and deployment differences on its downloads page.
Rank #2
- Confirm the required font files are installed or included in the deployment image or bundle.
- Confirm the fontconfig configuration and font directories are present and readable by the account running wkhtmltopdf.
- For containers or serverless bundles, include the font files and configuration in the deployed artifact, and point the process to the configuration location when necessary.
- Regenerate the minimal PDF from that same process and verify the affected characters, rather than relying on a successful test under a different user.
For its Amazon Linux 2 AWS Lambda example, the project sets FONTCONFIG_PATH=/opt/fonts for the bundled configuration. This is an example for that layout, not a general path to copy into other deployments.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →A CentOS 6.1 report using wkhtmltox 0.12.5 describes Fontconfig error: Cannot load default config file when invoked outside an interactive shell, despite fontconfig and dependencies being installed. Compare the process environment, configuration path, file permissions, and calling context; the report does not establish one universal repair. See the CentOS fontconfig issue.
Verify CSS web-font URLs and local-file access
For a CSS @font-face rule, test the font URL or path from the renderer’s point of view. Relative paths may resolve differently than expected, a container may have no network access to a remote font, and a local asset may be blocked by the renderer’s local-file policy.
- Check that the URL in
srcis valid from the process that runs wkhtmltopdf. For remote URLs, verify that the runtime can reach the host; for local files, verify the resolved path and permissions. - Check whether the font file is actually loaded rather than assuming that a browser’s successful rendering proves it is available to wkhtmltopdf.
- If the font is local, review
load.blockLocalFileAccessin the settings reference. Change access only if the local font is being blocked, and use the narrowest safe configuration; do not disable the protection indiscriminately. - Retest the PDF and inspect whether the intended family renders the affected characters.
Issue comments describe mixed results with alternate font formats and conversions across particular versions and environments. They do not support a dependable rule to convert every web font to TTF, OTF, WOFF, or SVG. See the format-related wkhtmltopdf issue.
Account for operating-system and package differences
A PDF created on Windows or macOS can differ from one created on Linux because the installed fonts, runtime libraries, package build, and configuration are not necessarily the same. Reproduce with the exact binary and deployment environment that produces the failing PDF before adopting an operating-system-specific workaround.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchThe wkhtmltopdf downloads page lists the 0.12.6 stable series and dates its release to June 11, 2020. It also explains that distribution builds vary and that installed fonts and fontconfig/freetype2 remain runtime dependencies. Check the current supported download list for your target, since availability can change. The project repository was archived on January 2, 2023, as indicated on its issue page; historical issue workarounds should not be treated as evidence of a fix in a maintained release.
Best Value
Use the symptom to choose the next check
| Symptom | First check | What the evidence establishes |
|---|---|---|
| Boxes or missing characters in one language or script | Whether an installed font has those glyphs and the CSS family resolves to it | A Chinese-text issue records a user’s missing-font remedy; the correct package depends on the script and distribution. Issue report. |
Fontconfig error: Cannot load default config file |
Configuration path, process environment, permissions, and container or service context | A CentOS report documents the error but does not establish a verified universal fix. Issue report. |
| Works on one operating system but not Linux | Exact build and package, installed fonts, and fontconfig/freetype2 runtime | Project documentation describes distribution-specific behavior; issue reports are environment-specific. Downloads page. |
@font-face is missing or substituted |
Font URL or path, local-file access setting, and whether the build can use that asset | Reports vary by format and environment; they do not establish a universal conversion recipe. Issue report. |
| Text encoding is corrupted | HTML or HTTP encoding and web.defaultEncoding |
Encoding configuration cannot supply missing glyphs. Settings reference. |
Or skip the browser setup
If your goal is a clean screenshot rather than a PDF rendered by wkhtmltopdf, ScreenshotNeo is a website screenshot API and MCP server. Its API takes one GET request with a URL and returns a PNG, JPEG, WebP, or PDF. Example using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for setup and parameters. ScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, with the page verdict and billing status reported in response headers. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000.
Sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Does setting UTF-8 install the font wkhtmltopdf needs?
No. Encoding controls how text is decoded; the system also needs a font with the required glyphs.
Is converting every web font to TTF a reliable fix?
No general conversion fix is established; reports vary by wkhtmltopdf version and environment.
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.
