The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If Unicode text is missing, replaced by boxes, or different from the browser preview in a wkhtmltopdf PDF, check three things separately: whether the input is actually UTF-8, whether the PDF-generating machine has fonts with the required glyphs, and whether wkhtmltopdf’s font fallback and runtime behave as expected. Start with a small test file, then test headers and footers independently. The --encoding utf-8 option and a UTF-8 locale can help with input decoding, but neither supplies missing font glyphs or guarantees browser-equivalent fallback.
Why are Unicode characters missing in my wkhtmltopdf PDF?
Unicode problems can occur at different stages of PDF generation. The HTML bytes may be decoded incorrectly; the renderer may lack a font covering a character; or its font fallback may differ from the browser used to preview the page. These causes can look alike in the final PDF, so changing encoding flags repeatedly is not a reliable diagnosis.
- Incorrect decoding: the input bytes, document declaration, or response charset do not agree.
- Missing glyphs: the machine running wkhtmltopdf has no suitable font for one or more characters.
- Font selection or fallback: a specified font lacks the characters and the renderer does not select the same fallback as Chrome or Firefox.
- A separate text path: header or footer text passed as command-line values may behave differently from body HTML.
These are documented failure modes, not a guarantee that one particular fix applies to every operating system or build. For example, reports describe both missing system fonts and cases where an explicit UTF-8 declaration was needed despite encoding and locale settings: wkhtmltopdf issue #3108 and issue #3233.
How do I make a minimal Unicode reproduction?
Use the exact wkhtmltopdf binary and rendering environment that produces the bad PDF. Reduce the input to the failing characters, a few known-good ASCII characters, and the font CSS used by the affected page. Save the file as UTF-8 and declare that encoding explicitly:
#1 Best Overall
![PDF Extra 2024| Complete PDF Reader and Editor | Create, Edit, Convert, Combine, Comment, Fill & Sign PDFs | Lifetime License | 1 Windows PC | 1 User [PC Online code]](https://m.media-amazon.com/images/I/41eZq4aiipL._SL160_.jpg)
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- LIFETIME License for 1 Windows PC or Laptop. 5GB MobiDrive Cloud Storage Included.
<!doctype html>
<html lang="zh">
<head>
<meta charset="utf-8">
<title>Unicode test</title>
</head>
<body>ASCII — 中文 — 日本語 — Ελληνικά — ქართული</body>
</html>Save this as unicode-test.html, then run the same executable and relevant options used in production:
wkhtmltopdf --encoding utf-8 unicode-test.html unicode-test.pdfOpen the resulting PDF and note precisely which characters fail. If this test works but the real document does not, add back its font declarations, templates, scripts, and headers or footers one at a time. If it fails, proceed through the checks below rather than assuming the browser preview proves the PDF renderer has the same inputs or fonts.
How do I check UTF-8 input and document declarations?
- Check the source bytes. Confirm the HTML file or generated template is actually saved as UTF-8, rather than merely labeled as UTF-8 after being encoded another way.
- Check the declaration. Include
<meta charset="utf-8">in the document head. When HTML arrives over HTTP, check that its response charset agrees with the document and actual bytes. - Check conversions before rendering. Look for template, database, or application code that converts text from another encoding before wkhtmltopdf reads it.
- Use the encoding option where appropriate.
--encoding utf-8can tell wkhtmltopdf how to interpret input, but it does not repair incorrectly encoded bytes or replace the document declaration.
A report against wkhtmltopdf 0.12.5 on Debian says an explicit UTF-8 meta declaration was needed even with the option and locale settings. That is a case report, not a universal rule: issue #3108.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How do I check fonts and missing glyph coverage?
If ASCII renders but a language, symbol, or handful of characters does not, inspect fonts on the machine that generates the PDF—not only on your workstation. A Linux container or server may not have the fonts installed on the desktop where Chrome displays the page.
Rank #2
- Edit PDFs with Ease. Modify text, images, and layouts directly within your PDF documents.
- Convert & Organize. Export PDFs to Word, Excel, or ePub, and organize files with ease.
- Read & Annotate. Enjoy intuitive reading modes and powerful tools to comment, highlight, and mark up PDFs.
- Create & Manage PDFs. Create new PDFs, combine multiple files, scan documents, and compress for easy sharing.
- Fill & Sign Forms. Complete forms and digitally sign documents with secure e-signature tools.
- Identify the affected script and characters. Test the exact text. A font that covers Latin letters may not cover Chinese, Japanese, Greek, Georgian, Thaana, or emoji.
- Inspect the CSS font stack. Check whether a custom font is explicitly selected and whether that font contains the needed glyphs. Temporarily test a known installed font with relevant coverage.
- Install an appropriate font on the rendering host. Use a package or font suitable for the target script and operating system. Package names and coverage vary by distribution, so verify the package for your deployment instead of copying a command intended for another system.
- Check visibility to the running process. In a container, make sure the font files are in the running image and visible to the same user that launches wkhtmltopdf.
Project reports describe Georgian and Greek rendering issues addressed by installing missing fonts on CentOS, and a Chinese rendering case on Ubuntu involving fonts-wqy-zenhei. Those examples are platform-specific, not universal installation instructions: issue #4456 and issue #3233.
The project’s downloads documentation notes that runtime font configuration depends on installed fonts and components including fontconfig and freetype2. A refreshed font cache or a successful font listing does not by itself prove that the renderer can shape and draw the required text: a Thaana report describes black squares despite an installed font and a refreshed cache (issue #3311).
Why does HTML look correct in Chrome but wrong in the PDF?
A browser preview is a useful comparison, but it is not proof that wkhtmltopdf will select the same fonts. A Windows issue reports Chrome and Firefox rendering characters that wkhtmltopdf did not; another report describes difficulty when a custom font lacked Japanese characters. Compare the CSS and available fonts in both environments, then test a font with known coverage in the wkhtmltopdf host: issue #4456 and issue #2573.
Simplify the font stack during diagnosis. Remove custom @font-face rules temporarily, specify an available family that covers the target script, and add fallback families explicitly where appropriate. If a setup relies on unicode-range, test without that mechanism: a 2014 issue reported unexpected behavior in a @font-face setup, but does not establish that all versions fail in the same way (issue #1837).
Rank #3
- Create and edit PDFs. Collaborate with ease. E-sign documents and collect signatures. Get everything done in one app, wherever you go.
- Edit text and images without jumping to another app.
- E-sign documents or request e-signatures on any device. Recipients don’t need to log in to e-sign.
- Convert PDFs to editable Microsoft Word, Excel, or PowerPoint documents.
- Share PDFs for collaboration. Commenting features make it easy for reviewers to comment, mark up, and annotate.
Why are non-ASCII characters missing from a PDF header or footer?
First compare a string rendered in the body with the same string in the header or footer. If body text works but the other region loses characters, investigate how the application or wrapper passes those values to wkhtmltopdf. A project issue reports non-ASCII characters being dropped when UTF-8 text was passed through command-line values by a Rails wrapper; the cause in another application may occur before the renderer receives the text or during rendering itself (issue #4228).
For diagnosis, place the same short test string in body HTML and in the production header/footer path. Check the wrapper’s argument handling and encoding at the point it constructs the command. Do not treat a successful body test as confirmation that header and footer arguments are correct.
How do I verify the wkhtmltopdf runtime?
- Record the full version and build string, operating system, and container image.
- Run the reproduction with the exact binary and command used in production.
- Confirm the required fonts and runtime font configuration are present in that environment.
- If using a generic binary, compare it with a distribution package intended for the target system; the project notes distribution packages may align dependencies more closely with that distribution.
The project’s downloads page describes fontconfig and FreeType as runtime dependencies and discusses distribution-specific packages: wkhtmltopdf downloads. A change in package or build is a variable to test, not a guaranteed Unicode fix.
What should I include in a useful bug report?
The project’s issue-reporting guidance asks for the version, a detailed description, and a reproducible test case. Include:
Rank #4
- Perfect Adobe Acrobat Pro alternative – lifetime license for Windows 10 and 11.
- EDIT text, images, pages, hyperlinks, designs in PDF documents. ORGANIZE PDFs.
- READ and Comment on PDFs – Intuitive reading modes & document commenting and mark up tools!
- CREATE, COMBINE, SCAN and COMPRESS PDFs.
- FILL forms & Digitally Sign PDFs. Work with Digital certificates
- The exact characters that render incorrectly and what appears in their place.
- A minimal HTML file, including its encoding declaration, and any CSS needed to reproduce the problem.
- The CSS font stack and relevant font-face rules.
- The full command line, including any wrapper or header/footer options.
- The wkhtmltopdf version/build, operating system, and container details.
- Whether the same HTML appears correctly in a browser, and which browser/environment you used.
Keep the example small enough to run directly. Issue discussions illustrate real problems, but their results belong to particular builds, languages, and platforms; validate any reported fix in your own rendering environment.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When should I consider another PDF renderer?
wkhtmltopdf’s GitHub repository was archived on January 2, 2023 (project repository). Its status page discusses Puppeteer/Chrome as a more modern browser-engine direction: wkhtmltopdf status. Consider migration if the required output cannot be made reliable with your supported build and deployment, but compare HTML/CSS behavior, font handling, PDF output requirements, accessibility needs, and operational constraints before switching. A different renderer is not a guarantee that every Unicode issue disappears. The status page also cautions against processing untrusted HTML without sanitization.
Or skip the browser setup
If the goal is to capture a webpage as an image or PDF rather than render HTML into a PDF from your own wkhtmltopdf process, ScreenshotNeo is a screenshot API and MCP server for developers. A single GET request can return a PNG, JPEG, WebP, or PDF. Example cURL request:
Free tools Windows power users keep installed
One-click scans. No signup required.
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 request options. ScreenshotNeo accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers indicate the page verdict and billing status. 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 with no card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month without a card.
Best Value
- ALL-IN-ONE SOLUTION – read, edit, convert, merge and protect your PDF files
- MAXIMUM FUNCIONALITY – create interactive forms, compare PDFs, bates numbering, find and replace text or colors, convert documents, OCR engine, comment, highlight, fill out and print forms, document protection and others
- EASY TO INSTALL AND USE – well-structured user-interface, in-program instructions, free tech support whenever you need it
- GREAT VALUE FOR MONEY - why spend a fortune if you can have maximum functionality at a reasonable price - this also fits the requirements of companies very well
Frequently Asked Questions
Does --encoding utf-8 install Unicode fonts?
No. It concerns input decoding; glyph coverage depends on fonts available to the rendering host.
Why does a font-cache refresh not necessarily solve black boxes?
A refreshed cache does not establish that the selected font has the needed glyphs or that rendering and shaping work correctly.
Does switching to Puppeteer guarantee correct Unicode PDFs?
No. The renderer change requires validation against your own fonts, content, output requirements, and deployment.
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.
