ScreenshotNeo

BlogHow-to

How to Fix Montserrat Font Rendering in wkhtmltopdf

Fix Montserrat rendering in wkhtmltopdf by checking fonts, Fontconfig, paths, builds, and runtime differences with a repeatable diagnostic process.

By the ScreenshotNeo team30 September 20269 min read

How to Fix Montserrat Font Rendering in wkhtmltopdf

Montserrat usually renders badly in wkhtmltopdf because the wkhtmltopdf process cannot discover or correctly rasterize the font in its own runtime. The browser on your workstation may have Montserrat installed while the server, container, Lambda bundle, or CI worker running wkhtmltopdf does not. Fix the rendering environment first, then simplify the HTML and verify the exact binary and operating system.

There is no universal Montserrat-only CSS declaration that repairs every wkhtmltopdf build. wkhtmltopdf uses Qt WebKit, and its Linux output depends on the Fontconfig and FreeType environment available to the process. Static builds still depend on system packages and runtime font configuration. The official downloads FAQ demonstrates configuring FONTCONFIG_PATH for a Lambda bundle, while Qt documentation describes Fontconfig and FreeType as the normal Linux font path. See the wkhtmltopdf downloads FAQ, project status page, and Qt font documentation.

What the symptom tells you

Symptom Likely cause First check
Montserrat is replaced by Arial or another sans-serif The font is missing or Fontconfig cannot see it Run fc-match Montserrat as the same user that runs wkhtmltopdf
Letters have odd spacing or weights A different Montserrat file or family face is selected Inspect the family and style with fc-match -v
Local HTML works, production PDF fails Different binary, OS image, font cache, or file permissions Record versions and compare the complete runtime
Web-font HTML works in a browser but not in PDF Old WebKit, blocked URL, certificate issue, or inaccessible CSS/font path Use a local reproduction and inspect network/path access
Text is too heavy, too light, or jagged Wrong face, missing weight, or rasterization differences Request an installed weight explicitly and compare the PDF at 100%

Step 1: Capture the exact rendering environment

Before changing CSS, write down the facts about the process that generates the PDF. wkhtmltopdf 0.12.6 was released on June 11, 2020 and is the stable series named on the project’s older downloads page; verify the version in your deployment rather than assuming every package is equivalent. Distribution packages and static builds can differ.

The font must be discoverable in the same runtime that launches wkhtmltopdf.
The font must be discoverable in the same runtime that launches wkhtmltopdf.
wkhtmltopdf --version
which wkhtmltopdf
uname -a
cat /etc/os-release
fc-match Montserrat
fc-match -v Montserrat | head -80

Run these commands inside the same container, VM, Lambda layer, or host and under the same account as the application. A successful result on your laptop proves only that your laptop’s process can find the font.

Step 2: Install Montserrat where wkhtmltopdf runs

Install the actual Montserrat font files on the rendering host. Installing them only on a developer workstation has no effect on a remote worker. Use a licensed source for the font files and keep the family faces you need, such as regular, medium, semibold and bold.

Linux host or container

sudo mkdir -p /usr/local/share/fonts/montserrat
sudo cp Montserrat-*.ttf /usr/local/share/fonts/montserrat/
sudo chmod 644 /usr/local/share/fonts/montserrat/*.ttf
sudo fc-cache -f -v
fc-list | grep -i montserrat
fc-match Montserrat

For a non-root application, place fonts in a user directory such as ~/.local/share/fonts and rebuild the cache as that user. In a container image, add the files during the image build and run the cache update there so new instances start with a populated cache.

Font family and weight names

The filename is not the CSS family name. Confirm the internal metadata:

fc-scan --format '%{family} | %{style}\n' /usr/local/share/fonts/montserrat/*.ttf

If the files report different family names, use the reported family in CSS or correct the font package. Declare the weights you actually installed:

body {
  font-family: "Montserrat", sans-serif;
  font-weight: 400;
}
strong, h1, h2 {
  font-weight: 700;
}

A request for weight 600 can be synthesized or replaced when only regular and bold faces are installed. That can change stroke thickness and spacing. Installing the required face and declaring its real weight is more predictable.

Step 3: Verify Fontconfig discovery

Fontconfig is the practical boundary between installed files and the application. Test it in the execution context, including environment variables and the service account.

echo "$FONTCONFIG_PATH"
fc-match -v "Montserrat:style=Regular" | grep -E 'family:|style:|file:'
fc-match -v "Montserrat:style=Bold" | grep -E 'family:|style:|file:'

If fc-match returns DejaVu Sans, Arial, or another fallback, fix discovery before investigating page styles. Check permissions on the font directories and confirm the service is not running in a restricted filesystem.

Bundled or Lambda runtimes

When fonts and Fontconfig data are bundled rather than installed system-wide, point the process at the bundle. The wkhtmltopdf FAQ shows FONTCONFIG_PATH as part of its AWS Lambda example. Adapt the path to your package:

export FONTCONFIG_PATH=/opt/fonts/etc/fonts
export FONTCONFIG_FILE=/opt/fonts/etc/fonts/fonts.conf
wkhtmltopdf input.html output.pdf

Do not copy these paths blindly. Confirm that the directory contains a valid fonts.conf and cache files, then run fc-match with the same variables. Rebuild the cache after changing the bundled files.

Step 4: Prove the font with a minimal HTML file

Remove application templates, JavaScript and unrelated CSS. This separates font loading from pagination and layout problems.

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    @page { size: A4; margin: 20mm; }
    body { font-family: "Montserrat", sans-serif; font-size: 16px; }
    .regular { font-weight: 400; }
    .bold { font-weight: 700; }
  </style>
</head>
<body>
  <p class="regular">Montserrat regular: Hamburgfons 0123456789</p>
  <p class="bold">Montserrat bold: Hamburgfons 0123456789</p>
</body>
</html>
wkhtmltopdf --enable-local-file-access minimal.html minimal.pdf

The --enable-local-file-access flag is needed when the HTML references local CSS, images or fonts and your build blocks local file access by default. Use it only when local resources are intentional. If the minimal PDF is correct, add your real stylesheet and content incrementally until the failing rule is identified.

Step 5: Check CSS, URL and file access

Montserrat can be installed correctly and still be unavailable because the HTML points at the wrong resource. Check each of these paths:

  • For a local @font-face, use a path readable by the wkhtmltopdf process and test with --enable-local-file-access.
  • For an HTTP font, verify DNS, TLS certificates, redirects and authentication from the rendering host. Old Qt WebKit builds may behave differently from current browsers.
  • Use an explicit format and weight in a minimal rule:
@font-face {
  font-family: "Montserrat";
  src: url("file:///opt/fonts/Montserrat-Regular.ttf") format("truetype");
  font-weight: 400;
  font-style: normal;
}

body { font-family: "Montserrat", sans-serif; }

Use file:/// only when the file is genuinely local and accessible. If you use a stylesheet URL, download it from the same host and inspect the resulting HTML. A browser’s developer tools cannot prove that wkhtmltopdf’s older WebKit can fetch the same URL.

Step 6: Compare the production binary and operating system

Capture the output of wkhtmltopdf --version, package name, OS image, architecture, Fontconfig version, font files and environment variables in both working and failing environments. Compare the complete inputs, not only the HTML. A distribution package may be patched differently from a downloaded static binary, and a static build still relies on runtime font configuration and other system dependencies.

The wkhtmltopdf status page describes its Qt 4/WebKit base as old: Qt 4 support ended in 2015 and the WebKit used by Qt 4 had not been updated since 2012. That age affects modern CSS and JavaScript as well as font loading. Treat the project dates as historical facts and verify the package you deploy.

Useful wkhtmltopdf options for font diagnosis

Option Use Diagnostic caution
--enable-local-file-access Allow intentional local CSS, font and image files Without it, local font URLs may fail
--print-media-type Use print media CSS Check that print rules do not override the font
--javascript-delay milliseconds Wait for client-rendered content Waiting does not repair a missing font
--debug-javascript Expose JavaScript console errors Useful when a script controls injected CSS
--load-error-handling ignore Continue after load errors Can hide a failed font or stylesheet; avoid while diagnosing

Common errors and fixes

“Fontconfig error: Cannot load default config file”

Cause: the process cannot find its configuration. Fix: provide a valid Fontconfig directory and set FONTCONFIG_PATH (and, where needed, FONTCONFIG_FILE) before starting wkhtmltopdf. Verify with fc-match.

Montserrat appears as a fallback

Cause: missing files, wrong family metadata, stale cache, or inaccessible directory. Fix: run fc-list and fc-match -v as the service account, rebuild the cache, and correct permissions.

Only bold or only regular text is wrong

Cause: the requested face is absent or mapped to a synthesized weight. Fix: install the matching face and declare its numeric weight in @font-face or CSS.

Local fonts work with one binary but not another

Cause: package and runtime differences. Fix: pin the known-good binary and OS image, or evaluate another renderer against your HTML, JavaScript, pagination, header/footer and deployment requirements.

Remote web fonts never load

Cause: network, certificate, redirect or access-control failure. Fix: test the URL from the renderer host, copy the font locally for a controlled reproduction, and inspect stderr. Do not assume a successful browser load transfers to Qt WebKit.

The font is correct but the PDF still looks different

Cause: rasterization, hinting, scale, printer CSS or an old WebKit layout difference. Fix: compare at 100% zoom, disable unrelated CSS, test print media explicitly, and compare the exact runtime. Font substitution and antialiasing are separate issues.

Performance, reliability and deployment checklist

  • Bake font files and Fontconfig cache into the image or deployment artifact instead of downloading them during every job.
  • Keep the wkhtmltopdf version and OS image pinned so output does not change unexpectedly.
  • Use a minimal fixture in CI that checks family, regular weight, bold weight and representative punctuation.
  • Log the binary version, OS image identifier, Fontconfig path and input URL with each PDF job.
  • Set a process timeout and clean up child processes. A font diagnosis cannot be trusted if the job is silently killed.
  • Do not treat a fallback PDF as successful. Inspect stderr and, where possible, compare rendered text or a reference image.
  • For dynamic pages, check JavaScript completion and pagination separately from font discovery.

These checks improve repeatability, but wkhtmltopdf’s legacy rendering stack can still differ across platforms. If your requirements include modern CSS or JavaScript, evaluate a maintained browser-based renderer using the comparison axes above.

A managed capture service can remove common overlays before rendering.
A managed capture service can remove common overlays before rendering.

Or skip the browser setup

If your goal is a clean visual capture rather than a wkhtmltopdf-specific PDF pipeline, ScreenshotNeo provides a website screenshot API and MCP server. It accepts one GET request and returns PNG, JPEG or WebP, with options for full-page capture, device and viewport settings, custom CSS and JavaScript, waiting rules, headers, cookies, user agents and more. See the ScreenshotNeo API documentation for the complete option list.

cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

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}`);

ScreenshotNeo removes cookie banners, newsletter popups and chat widgets before capture. Bot checks, blank pages, failed loads and cache hits cost nothing, and response headers identify the page verdict and whether the shot was billed. Its MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. The Free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

When to replace wkhtmltopdf

Consider another renderer when you cannot make the deployment reproducible, when modern CSS or JavaScript is required, or when the project’s old Qt/WebKit base conflicts with your document requirements. Compare fidelity to your existing HTML/CSS, JavaScript support, pagination and headers/footers, runtime maintenance, and packaging. Keep the minimal Montserrat fixture and a representative production page as acceptance tests during the comparison.

FAQ

Does adding !important fix Montserrat?

No. It can resolve a CSS cascade conflict, but it cannot install a missing font or repair Fontconfig discovery.

Should I embed Montserrat as a data URL?

It can isolate network and file path problems, but it does not remove renderer or FreeType differences. Use it as a diagnostic experiment, then verify the deployed runtime.

Why does a static wkhtmltopdf binary still need system setup?

The project’s FAQ explains that static builds still rely on system packages and runtime configuration, including Fontconfig and FreeType.

What should I include in a bug report?

Include the wkhtmltopdf version and build, OS or container image, architecture, Fontconfig output, how Montserrat is installed or loaded, the minimal HTML, and the generated PDF.

Can ScreenshotNeo reproduce my exact wkhtmltopdf output?

No. ScreenshotNeo is a separate capture service. Use it when you need a clean website screenshot or PDF capture without maintaining a browser runtime; validate its output against your page requirements.