The reliable fix is to make every layer agree on UTF-8: save the HTML as UTF-8 bytes, declare <meta charset="utf-8"> near the start of <head>, return a matching HTTP Content-Type for URL input, and use --encoding utf-8 (or your wrapper’s equivalent) as a fallback. If text is replaced by boxes or only one writing system fails, install a font that contains those glyphs; that is a font-coverage problem, not an encoding problem.
Start with the symptom
Character failures in wkhtmltopdf usually fall into three different classes. Identify yours before changing options:
| Symptom | Likely layer | First check |
|---|---|---|
| Garbled text such as mojibake throughout the page | Bytes, HTTP charset, or document declaration | Inspect the saved bytes and the response Content-Type; add an early UTF-8 declaration |
| A URL works, but the same downloaded HTML file fails | Input-path metadata | Compare the URL response headers with the local file and set the fallback encoding |
| Chinese, Japanese, Korean, emoji, or symbols become boxes or vanish | Font coverage | Check fonts installed on the machine running wkhtmltopdf |
| Body text is correct but header or footer text is broken | Separate header/footer input | Use UTF-8 header/footer HTML and declare its charset |
Make the HTML bytes UTF-8
Save the source in the intended encoding
A meta tag tells the parser how to interpret bytes; it cannot convert bytes that were saved in another encoding. Open the actual source in an editor that displays the current encoding, convert it to UTF-8, and save it again. For generated HTML, configure the template writer or serializer to emit UTF-8 rather than relying on a platform default.
Check the bytes when the symptom is severe. A file that contains UTF-8 data must be read as UTF-8 by the process that creates it and by wkhtmltopdf. If a legacy encoding was used, re-save or transcode the source first; changing only a command-line flag can make already-misencoded text worse.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Put an explicit declaration at the top of <head>
Use the short HTML5 form before other content that could be parsed as text:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Unicode test — café 日本語 中文 😀</title>
</head>
<body>
<p>Accents: café, naïve, señor</p>
<p>CJK: 日本語 中文 한국어</p>
<p>Symbols: © ✓ € and emoji 😀</p>
</body>
</html>If your templates require the older syntax, use an equivalent declaration such as <meta http-equiv="Content-Type" content="text/html; charset=utf-8">. A 2021 wkhtmltopdf Unicode issue report specifically found that Unicode input failed unless the HTML contained that HTTP-equiv UTF-8 declaration.
Make URL responses and local files agree
URL input
When wkhtmltopdf loads a URL, the HTTP response participates in encoding detection. Inspect the response’s Content-Type; a charset that conflicts with the document can override the HTML declaration during parsing. Configure the server to return a UTF-8 content type, for example text/html; charset=utf-8, and keep the HTML meta declaration as a defensive, portable signal.
Do not assume that seeing correct characters in a browser proves the response is unambiguous. Browsers may recover from malformed declarations differently from the Qt WebKit engine used by your wkhtmltopdf build. Compare a browser view, the raw response headers, and wkhtmltopdf output from the same URL.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Downloaded or generated local HTML
A saved file no longer carries the HTTP charset metadata that accompanied the URL. That explains the common “URL works, local copy fails” case. Preserve a UTF-8 declaration in the file and pass an explicit fallback:
wkhtmltopdf --encoding utf-8 input.html output.pdfThe official usage documentation describes --encoding <encoding> as the default text encoding for input. It is a fallback for content that does not specify an encoding; it is not a repair for incorrectly encoded bytes.
Standard input and generated pipelines
If another process pipes HTML to wkhtmltopdf, ensure that process writes UTF-8 bytes and that the HTML begins with the declaration above. Apply the same option when the stream has no reliable declaration:
generate-report | wkhtmltopdf --encoding utf-8 - report.pdfKeep the producer and consumer in the same encoding contract. Logging or shell redirection that transcodes the stream can reintroduce the problem before wkhtmltopdf starts.
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 problemsRank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Configure wrappers and libraries
Language bindings expose the same concept under different names. Set the wrapper’s input encoding or default-encoding option to UTF-8 and still include the meta element in every template. In libwkhtmltox settings, web.defaultEncoding is used to guess the encoding when content does not specify one; set it to utf-8.
Keep this setting scoped to the web-page input. Header and footer documents are separate inputs and need their own declarations. Verify the generated command or options object in logs so a deployment environment is not silently using a different default.
Distinguish encoding from missing glyphs
Recognize the font symptom
If Latin text is correct but Chinese, Japanese, Korean, mathematical symbols, or emoji appear as empty squares, question marks, or disappear, the text may already be decoded correctly. The rendering host simply lacks a font with those glyphs, or the selected CSS font has no suitable fallback.
Install a font with the required coverage on the machine or container that runs wkhtmltopdf, then refresh the font cache using the operating system’s normal package and font-management procedure. A wkhtmltopdf issue discussing missing Chinese fonts gives fonts-wqy-zenhei as an Ubuntu example; availability and package names vary by distribution.
Recommended Free Tools
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Test coverage separately
Create a small UTF-8 page containing the exact scripts and symbols you need. Render it with the same user, container image, CSS, and wkhtmltopdf binary used in production. If the characters work after selecting an appropriate fallback font, stop changing encoding flags. If they remain garbled, return to byte and charset checks.
Headers and footers are independent inputs
Command-line header and footer text can fail while the body is perfect because they are parsed separately. Avoid putting non-ASCII text directly in a command-line argument when possible. Instead, place dynamic content in a UTF-8 HTML header or footer file, add the UTF-8 meta declaration to that file, and reference it with the relevant header-html or footer-html option.
<!doctype html>
<html>
<head><meta charset="utf-8"></head>
<body><span>Invoice — José 李</span></body>
</html>An issue report describes this UTF-8 header/footer HTML approach as working for non-ASCII footer content. Treat it as build-specific evidence, then validate with the exact wkhtmltopdf package and operating system you deploy.
A repeatable diagnostic procedure
- Reduce the case. Render a tiny page containing an accented character, one CJK sample, and a symbol or emoji. This separates a parser problem from application complexity.
- Verify bytes. Confirm the template, intermediate file, and piped stream are UTF-8, not merely labeled UTF-8.
- Declare early. Put
<meta charset="utf-8">near the beginning of<head>in the body, header, and footer documents. - Inspect HTTP. For URL input, check the response
Content-Typeand remove a conflicting charset. - Apply the fallback. Run with
--encoding utf-8; in a binding, setweb.defaultEncodingor its equivalent. - Check fonts. If only particular scripts fail, install and select fonts that contain those glyphs.
- Compare paths. Render the URL, a UTF-8 local copy, and stdin with identical options. The first path that differs identifies the layer to fix.
- Pin the environment. Record the wkhtmltopdf build, operating system, installed fonts, wrapper version, and command-line options alongside a passing fixture.
Common failures and fixes
| What you see | Cause to investigate | Fix |
|---|---|---|
| Every accented character is mangled | Wrong source bytes or conflicting response charset | Re-save as UTF-8, add the early meta tag, correct HTTP headers, then use --encoding utf-8 |
| Only the local file is broken | Local file lost URL charset metadata | Embed the declaration and pass the fallback option |
| Chinese becomes squares | No installed font glyphs | Install a CJK-capable font and set a CSS fallback; do not rely on encoding flags alone |
| Emoji vary by machine | Font coverage differs between hosts | Install a font covering the required emoji and test on the production image |
| Footer is broken, body is fine | Footer is a separate, undeclared document | Use UTF-8 footer HTML with its own meta declaration |
| One server works, another fails | Different patched builds, Qt versions, fonts, or wrapper defaults | Compare environment details and run the same minimal fixture on both |
Reliability, performance, and cost considerations
Encoding fixes are normally low-cost compared with repeatedly debugging corrupted PDFs. The most reliable deployment is deterministic: UTF-8 templates committed to source control, explicit response headers, a fixed wkhtmltopdf build, and a container or host image with documented fonts. Add a regression fixture to CI that checks representative accents, CJK text, symbols, and header/footer content.
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 minuteBest Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Use the smallest reproduction when diagnosing; it renders faster and makes byte-level comparisons easier. Once fixed, keep the same options for production rather than adding multiple competing charset declarations or random font substitutions. Distribution builds and issue reports are not guarantees for every platform, so validate the exact binary you ship.
Or skip the browser setup
If your real requirement is a clean image or PDF of a web page rather than control of a local wkhtmltopdf process, ScreenshotNeo provides a single screenshot API call. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the result with X-Page-Verdict and X-Billed headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import 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)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}`);See the complete option list and request details in the ScreenshotNeo documentation. The service supports PNG, JPEG, WebP, and PDF; full-page and selector capture, device and viewport settings, retina scale, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agents, timezone and geolocation, resizing, chosen cache TTLs, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. Parameter names used by other screenshot APIs also work, which can simplify migration.
The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan, and yearly billing gives two months free. Create a free ScreenshotNeo account to try it without a card.
Frequently Asked Questions
Does adding --encoding utf-8 convert a Latin-1 file?
No. It supplies a default for input that does not declare an encoding. Re-save or transcode the source bytes to UTF-8 first.
Why does a browser display the page correctly while wkhtmltopdf does not?
Browsers and the Qt WebKit engine can recover from conflicting or missing declarations differently. Compare raw bytes, HTTP headers, the early meta tag, fonts, and the exact wkhtmltopdf build.
Should I use the HTML5 meta tag or the HTTP-equiv form?
Either explicitly declares UTF-8. Put the HTML5 form near the start of <head>; use the HTTP-equiv form when a legacy template requires it.
Can CSS fix an encoding problem?
CSS can select a font with the needed glyphs, but it cannot repair incorrectly decoded bytes. Diagnose bytes and charset declarations before changing fonts.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
