How to Fix Character Encoding Issues in wkhtmltopdf
Fix mojibake, missing accented or CJK characters, and emoji in wkhtmltopdf by checking the source bytes, HTML and HTTP charset, fallback encoding, and font coverage.

Start by checking the HTML bytes and the renderer’s font coverage. Save the source as UTF-8, declare UTF-8 near the beginning of <head>, and make sure a URL’s HTTP response does not advertise a conflicting charset. Then try wkhtmltopdf --encoding utf-8 as a fallback for undeclared input. That option cannot repair bytes that were saved in another encoding, and it cannot supply glyphs missing from the fonts installed on the rendering host.
This distinction explains many confusing cases: a PDF may show mojibake when the bytes are decoded incorrectly, or boxes and missing characters when the text is decoded correctly but no usable font contains the glyph. A URL and a local copy of the same HTML can also behave differently because the URL response includes HTTP headers that a file on disk does not.
1. Identify which kind of failure you have
Look closely at the output and compare it with the source text before changing options. The symptom narrows down the cause:

| PDF symptom | Likely cause | First check |
|---|---|---|
Accented text becomes sequences such as é or otherwise looks garbled |
Bytes were decoded using the wrong character set, or the declared charset is wrong | Inspect the file bytes, HTML declaration, and HTTP Content-Type |
| Text is missing, replaced by squares, or fails only for Chinese, Japanese, Korean, or symbols | The chosen font or its fallbacks lack those glyphs | Install and select a font with the required script coverage |
| The page body is correct, but header or footer text is missing | Header/footer input has a separate encoding path | Use UTF-8 header/footer HTML and declare UTF-8 in that document |
| A URL works but the saved local file fails | The URL’s response headers supplied charset information absent from the local file | Compare the response header and local document declaration |
Do not start by changing fonts when the entire page is mojibake. Conversely, changing the charset repeatedly will not add Chinese glyphs to a Latin-only font.
2. Save the document bytes as UTF-8
A charset declaration tells the renderer how to interpret bytes. It does not convert bytes that were saved in another encoding. If a source file contains legacy-encoded text but is labeled UTF-8, correct the file by converting it to UTF-8 at the source or export step.
For a controlled diagnostic, create a small UTF-8 fixture containing the characters that fail in your real document, such as café — 東京 — 한글 — مرحبا. Ensure the editor or generator actually writes UTF-8. Check the encoding setting in the tool producing the file; adding a meta tag after incorrect bytes were written is not a conversion.
When data originates in a database, template, CSV, or another service, inspect it before the HTML renderer sees it. The wrong conversion can happen upstream, for example when a string is decoded using one charset and then encoded or labeled as another. Preserve the text as Unicode inside your application and encode the completed HTML as UTF-8 once.
3. Declare UTF-8 early in every HTML document
Place the short declaration near the start of <head>, before scripts, stylesheets, or substantial text:
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Encoding check</title>
</head>
<body>
<p>café — 東京 — 한글</p>
</body>
</html>
If a template or older environment needs the equivalent content-type form, use:
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
Use one clear declaration rather than multiple contradictory declarations. Put it in every document wkhtmltopdf loads independently: the main page and any separate header or footer HTML. A reported Unicode issue found that adding the content-type meta declaration fixed input for that particular wkhtmltopdf build; treat the issue report as diagnostic evidence, not a guarantee for every package or platform. See the [wkhtmltopdf Unicode issue](https://github.com/wkhtmltopdf/wkhtmltopdf/issues/5006).
4. Check HTTP headers when converting a URL
When the input is a URL, inspect the response’s Content-Type header. It should identify HTML and, where a charset is specified, agree with the actual UTF-8 bytes and the document declaration. A conflicting response charset can affect parsing even when the HTML contains a UTF-8 meta tag.
For example, compare the URL response with the downloaded source. If the URL works but the downloaded file does not, check whether the local copy retained the original bytes and the HTML declaration. A local file has no HTTP response header to provide the missing charset. Add the meta declaration and verify the file itself is UTF-8. The behavior has varied across reported builds and input paths; the [wkhtmltopdf issue discussion](https://github.com/wkhtmltopdf/wkhtmltopdf/issues/3233) describes URL-versus-local input reports and also illustrates why a missing font can look like an encoding issue.
5. Use the command-line encoding option as a fallback
The official usage documentation defines --encoding <encoding> as the default text encoding for input. It is useful when an input does not specify its encoding properly. It does not override the need for correct source bytes and a correct declaration, and it cannot fix missing font glyphs.
For a local file:
wkhtmltopdf --encoding utf-8 input.html output.pdf
For a URL:
wkhtmltopdf --encoding utf-8 https://example.com/page output.pdf
Use the option before the input it applies to. wkhtmltopdf accepts global options before an input object; when a command contains multiple page objects, verify the option scope against the command structure and your installed version. Confirm available options with wkhtmltopdf --extended-help or the help output for the installed binary. The [official usage documentation](https://wkhtmltopdf.org/usage/wkhtmltopdf.txt) documents the encoding option.
Do not add unrelated request headers such as a made-up charset header to try to fix an HTML document. The response server controls Content-Type; a request header is not a replacement for correcting the document or the server response.
6. Configure library and framework bindings
In libwkhtmltox settings, web.defaultEncoding is the fallback encoding used when content does not specify one properly. Set it to UTF-8 in the wrapper’s object or web settings, and keep the UTF-8 meta declaration in the generated template. The [libwkhtmltox settings reference](https://wkhtmltopdf.org/libwkhtmltox/pagesettings.html) documents web.defaultEncoding.
Framework wrappers use different APIs and configuration names, so use the wrapper’s documented mechanism for passing web settings rather than assuming a command-line flag is automatically supported. A robust integration does both of the following:
- Sets the wrapper’s default encoding to
utf-8. - Emits
<meta charset="utf-8">in every HTML template, including header and footer templates.
If a wrapper writes intermediate files, inspect those exact files. The browser-facing template may be UTF-8 while a temporary file or generated header has been converted incorrectly before wkhtmltopdf reads it.
7. Fix missing glyphs by installing fonts
Once you have confirmed that text is decoded correctly, check whether the rendering host has fonts that contain the missing script. This matters especially in minimal Linux containers and servers. A developer workstation may have broad font coverage that the production image lacks.
Install an appropriate font package for the operating system and configure CSS to use a font available on the host. For example, a wkhtmltopdf issue discussion cites fonts-wqy-zenhei as an Ubuntu example for Chinese characters. Package names and coverage vary by distribution, so confirm the package and font family available in your environment rather than copying the example blindly. See the [Chinese-font issue discussion](https://github.com/wkhtmltopdf/wkhtmltopdf/issues/3233).
body {
font-family: "Noto Sans", "WenQuanYi Zen Hei", sans-serif;
}
The family list is a preference list; each family must exist on the rendering host. Rebuild or restart the relevant container or service if needed, then regenerate the PDF. Emoji are a special case: a font may lack the specific emoji, and the renderer may not support the color-font format or fallback behavior you expect. Test the exact symbols in the deployed environment. If decorative emoji are optional, use a supported text alternative or an image asset when your document requirements permit it.
8. Treat headers and footers as separate HTML inputs
Command-line header and footer text can fail independently from the body. If the body is correct but a non-ASCII footer is dropped or corrupted, move the dynamic text into a small UTF-8 HTML file and pass that file through the relevant header or footer option. Add a charset declaration inside that file too.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
</head>
<body>
<div>Résumé — 東京</div>
</body>
</html>
Keep the file’s bytes in UTF-8 and verify how your wrapper passes dynamic values into it. A header/footer HTML workaround has been reported for a specific case where command-line footer text skipped non-ASCII characters, documented in the [wkhtmltopdf header/footer issue](https://github.com/wkhtmltopdf/wkhtmltopdf/issues/4228). This is build-specific evidence rather than a promise that every header/footer issue has the same cause.
9. A repeatable debugging sequence
- Reduce the case. Make a one-page HTML file with just the failing characters and a known font.
- Check the bytes. Confirm the file is actually saved as UTF-8, not merely labeled as UTF-8.
- Check declarations. Put one UTF-8 meta declaration at the beginning of each HTML input.
- Check HTTP metadata. For URL input, inspect
Content-Typeand fix a conflicting server charset. - Apply the fallback. Run with
--encoding utf-8, or setweb.defaultEncodingin a binding. - Test fonts. If only particular scripts or symbols fail, install and select a font with those glyphs.
- Isolate headers and footers. Test body, header, and footer independently, then restore the complete template.
- Compare environments. Record the wkhtmltopdf version, distribution package, operating system, and installed fonts for a working and failing host.
10. Troubleshooting common errors
| Problem | Cause to investigate | Fix |
|---|---|---|
--encoding utf-8 has no effect |
The file has the wrong bytes, an HTTP header conflicts, or the issue is font coverage | Validate bytes and declarations first; use the option only as a fallback; test a font for script-specific failures |
| Saved HTML fails while its URL works | The URL response provides charset metadata missing from the local input | Preserve UTF-8 bytes and add an early meta declaration to the local HTML |
| Chinese characters become boxes | No usable CJK font is installed or selected | Install a font with the needed glyphs and configure CSS to use it |
| Only footer characters disappear | Footer text is handled separately from the page body | Use a UTF-8 footer HTML document with its own charset declaration |
| Text is garbled in every language | Wrong source encoding or conflicting metadata is likely | Check the bytes, HTTP response, and document declaration before changing fonts |
| It works locally but fails in a container | The production image may have different fonts, packages, or wkhtmltopdf build | Reproduce with the same binary and install the required fonts in the image |
11. Reliability, performance, and cost considerations
For repeatable output, make encoding and fonts explicit in the document and deployment image. Pin the wkhtmltopdf build used by your application, record its version, and keep a small Unicode fixture in your release checks. A distro package and a separately distributed build may behave differently; issue reports should guide diagnosis, not be treated as universal specifications.

Encoding corrections add little rendering work. Installing fonts increases the deployment image and may affect font lookup, but is the appropriate fix when glyph coverage is missing. Large fonts and documents can affect image loading and layout, so test output size and generation time with representative pages. Avoid converting encodings multiple times in the request path; normalize upstream and emit UTF-8 once.
wkhtmltopdf itself is software you operate, so costs depend on the compute, storage, and maintenance of your deployment; there is no per-shot fee from the command-line tool described here. Budget for container images, font packages, queue capacity, and operational time. Keep failed outputs and diagnostic logs scoped appropriately if documents contain sensitive data.
Or skip the browser setup
If the task is to capture a webpage as an image or PDF rather than debug a wkhtmltopdf installation, [ScreenshotNeo](https://screenshotneo.com) offers a website screenshot API and MCP server. Its one-call API returns PNG, JPEG, WebP, or PDF. See the [API documentation](https://screenshotneo.com/docs/) for parameters and options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
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)
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 accepts cookie and consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. One thousand screenshots a month are free with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Does UTF-8 support mean every character will appear?
No. UTF-8 describes how text is encoded. A font still needs the glyph, and the renderer must be able to use that font and its format.
Should I use utf8 or utf-8?
Use utf-8 consistently in HTML and command examples. The important part is that bytes and declarations agree; follow the accepted spelling for the setting in your binding.
Can I fix incorrect source bytes by changing the PDF command?
Not reliably. Convert or regenerate the source as UTF-8, then declare it accurately. A default encoding option only helps interpret otherwise unspecified input.
Why does only emoji fail?
The selected fonts may not contain those emoji, or the rendering stack may not handle the font’s color format. Test the target symbols and fonts on the same host and build used in production.


