Recommended Free Tools
If Helvetica does not appear in a PDF made with wkhtmltopdf, check the environment that runs the conversion—not just the CSS. wkhtmltopdf needs the requested font to be available and discoverable at runtime, and CSS must actually apply that font to the rendered content. If either condition fails, the PDF may use a substitute. The reliable fix is to verify the font, CSS, and runtime configuration on the production host, then inspect a PDF generated there.
Why Helvetica can fail in wkhtmltopdf
A CSS declaration such as font-family: Helvetica, sans-serif; requests a family; it does not install that family on the machine creating the PDF. wkhtmltopdf depends on the runtime font setup, including installed fonts and the fontconfig and FreeType components. The project documentation specifically cautions that actual installed fonts and runtime configuration matter.
There are four separate points to check:
- Font availability: Is the desired font installed or bundled where wkhtmltopdf runs?
- Font discovery: Can the process’s font configuration find it?
- CSS application: Does the rendered element actually use the family, and does any referenced font file load?
- Environment differences: Does the production OS or container have the same fonts and configuration as the machine where the HTML was previewed?
Changing the CSS alone cannot fix a missing font file or a fontconfig path that points somewhere else.
Diagnose the conversion environment first
1. Run font discovery where wkhtmltopdf runs
On Linux, community guidance for this issue uses fc-list to inspect installed font families. Run it inside the same container, VM, server, or serverless package that invokes wkhtmltopdf—not only on your workstation.
Outdated 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 matchPC 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 & 11#1 Best Overall
fc-listLook for the family name reported by the system. Use that reported name in CSS rather than assuming the host recognizes a particular spelling or alias. If the font is absent, install or bundle a permitted font file as appropriate for your deployment. After adding font files, rebuild the font cache using the cache-update command for your distribution, then run fc-list again to confirm discovery.
Installing a font on a developer’s desktop does not install it in a production image or serverless deployment. Make font files and any required font configuration part of the build or deployment process, and check the font’s license permits your intended use and distribution.
2. Confirm the CSS reaches the content
Set the family on the elements whose appearance matters. A basic check is to apply it to the body and inspect any more-specific rules that could override it:
body {
font-family: Helvetica, Arial, sans-serif;
}The fallback list is useful only if a later family is available and acceptable; it does not make Helvetica appear when Helvetica is missing. If you use @font-face, verify both that the declaration’s family identifier matches the name used by the element and that the font resource resolves from wkhtmltopdf’s process. A declaration that is never used by rendered content will not change the PDF.
Free tools Windows power users keep installed
One-click scans. No signup required.
@font-face {
font-family: "ReportSans";
src: url("file:///absolute/path/to/font-file.ttf") format("truetype");
}
body {
font-family: "ReportSans", sans-serif;
}This is a pattern, not a guaranteed cross-platform recipe: use a real, accessible font path and a format supported by the deployed build. If the HTML is generated remotely or runs in a restricted package, check the resource from that process’s point of view. A path that exists on your laptop may not exist in the container.
3. Generate and inspect a production-like PDF
Run the same conversion command and package that production uses. Compare the resulting PDF with the intended appearance, and inspect its font information with a PDF inspection tool available in your environment. Record the OS or distribution, wkhtmltopdf build, font family and version, fontconfig paths, and observed PDF font information. The issue reports in the project repository describe differing output across operating systems and setups; they are examples, not a compatibility guarantee or a universal diagnosis.
Rank #3
Choose a fix that fits the deployment
Install the font on the host
For a managed Linux machine or VM, installing the required font and refreshing the font cache can be the simplest approach. Confirm that the conversion service runs with access to the installed files and the relevant font configuration. A service account, container, or separate worker may not see the same font directories as an interactive shell.
Bundle fonts and configure fontconfig
For containers and packaged runtimes, include the font files and configuration in the artifact, then make sure the runtime’s font discovery points to them. The wkhtmltopdf project download page documents an AWS Lambda example that bundles its distribution package and sets FONTCONFIG_PATH=/opt/fonts. That path belongs to that documented example; do not copy it blindly into a different runtime. Verify the paths and libraries against the exact package and OS you deploy.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsThe project notes that generic Linux binaries are constrained by system-library compatibility and recommends distribution-specific packages where available. Its documentation also identifies installed fonts, fontconfig, and FreeType as runtime dependencies. A binary that starts successfully can still produce the wrong typography if font discovery is misconfigured.
Use a substitute or embed a font only when acceptable
If the exact Helvetica face is not available, decide whether a substitute is acceptable for the document’s purpose. A generic CSS fallback can keep text legible, but it may alter line breaks, spacing, and page layout. If exact appearance matters, use a permitted font asset and confirm it is available to the converter.
Community answers report embedding a font through CSS, including Base64, as a workaround. This is not an official guarantee for every wkhtmltopdf build. Embedding can make the HTML larger, and font licensing may limit embedding or redistribution. Test the result using the installed build and target OS rather than treating an embedded declaration as proof the PDF will use that face.
Why the same HTML can look different on another machine
Font matching depends on the installed families and the runtime configuration, not simply on the HTML source. Historical issue reports describe differences between macOS and Ubuntu, and between Linux and Windows; another report concerns font-family and fontconfig behavior in a container. These reports establish that environment-specific differences occur, but they do not identify one root cause for every deployment.
Best Value
When a local PDF looks right but a deployed PDF does not, compare the complete runtime rather than only the wkhtmltopdf version. Capture the OS or distribution, package/build, installed family names and versions, fontconfig search paths, and PDF-observed font information for both environments. Reproduce using the production image or bundle before changing the CSS to compensate for a deployment-only problem.
The wkhtmltopdf GitHub repository issue pages identify the project as archived and read-only from January 2, 2023. Its historical issue reports are not a current compatibility matrix. For a long-lived system, factor the project’s maintenance status into renderer decisions and validate any fix against the exact package you intend to keep using.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your actual requirement is a clean website screenshot rather than a PDF rendered with wkhtmltopdf, ScreenshotNeo is a website screenshot API and MCP server; it is not a fix for Helvetica in wkhtmltopdf or a substitute for controlling PDF typography. One GET request can return an image or PDF. Example cURL request:
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. Before capture, it can accept cookie or consent banners and remove known consent platforms, newsletter popups, and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server provides screenshot and PDF tools for AI agents. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo’s free plan.
Troubleshooting by symptom
| Symptom | Likely check | Next action |
|---|---|---|
| PDF uses a different-looking font everywhere | The requested family may not be installed or discoverable in the conversion environment. | Run fc-list there; install or bundle an appropriate font, refresh the font cache, and regenerate the PDF. |
| Font works locally but not in a container or serverless run | The deployed image may have different fonts, libraries, or fontconfig paths. | Compare the runtime details and ensure bundled files and configuration are included and reachable. For Lambda, use the project’s example only as a scoped reference. |
@font-face is present but has no visible effect |
The element may not use the declared family, or the font URL may fail from wkhtmltopdf’s process. | Match the CSS family identifiers, apply the family to the rendered element, and verify the font resource path in the production environment. |
| Text wraps differently after changing fonts | A different face or fallback can change text metrics and page layout. | Confirm which font the PDF actually uses; use the intended permitted face if layout fidelity is required, then recheck pagination. |
| Only one OS produces the expected result | Font availability and matching differ between environments; historical reports document such differences. | Record and compare OS, package/build, font versions, and fontconfig paths; test the target environment rather than assuming version equality is enough. |
Deployment checklist
- Run font discovery in the same runtime that executes wkhtmltopdf.
- Use the system-reported family name and ensure CSS applies it to the content.
- Verify every referenced font file is packaged and reachable from the converter.
- Refresh font caches when adding files, using the deployment distribution’s appropriate command.
- For containers or serverless packages, validate fontconfig and library paths in the built artifact.
- Generate a test PDF in a production-like environment and inspect the embedded or reported font information.
- Check font licensing before embedding or redistributing font files.
Frequently Asked Questions
Does declaring Helvetica in CSS install it for wkhtmltopdf?
No. CSS selects a family; the runtime must have an available, discoverable font for that selection.
Can I use a Base64-embedded font instead?
It is a community-reported workaround, not a universal guarantee. Confirm licensing and test it in the exact deployed build.
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.
