Puppeteer uses the fonts available to the Linux environment that launches Chrome—not the fonts installed on your Mac or Windows desktop. Fix missing glyphs, tofu boxes, wrong fallbacks, and layout shifts by installing the required fonts and a UTF-8 locale in the runtime image, loading every web-font weight before capture, and keeping Puppeteer, Chrome for Testing (or Chromium), and the base image compatible. If spacing still differs after that, compare Linux font-rendering settings.
Start with a reproducible diagnosis
Write down the environment for the failing capture before changing it:
- Operating system and Docker base image (including whether it is Alpine).
- Puppeteer version and the browser binary/version actually launched.
- Locale variables such as
LANGandLC_ALL. - Whether the run is local, in Docker, CI, or a serverless runtime.
- The exact URL, characters, CSS weights/styles, and capture method (
page.screenshot()orpage.pdf()).
A desktop preview proves only that the desktop has the font. Chrome in a container or CI runner has a different filesystem and may silently select a fallback face.
Use a glyph specimen, not a sentence
Capture a test page containing the real character sets used by your application: Latin, CJK, Arabic, Hebrew, Thai, and emoji as applicable. Boxes (tofu), visibly different letterforms, or changed line breaks usually indicate missing glyph coverage or fallback. Compare the same specimen locally and in the target runtime.
#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.
Install system fonts and a UTF-8 locale
Install fonts in the image that runs Chrome. Puppeteer’s Debian guidance includes fonts-liberation; its broad-charset Docker example adds Japanese, Chinese, Thai, Arabic, and broad Unicode packages.
FROM node:20-bookworm-slim
ENV LANG=en_US.UTF-8
ENV LC_ALL=en_US.UTF-8
RUN apt-get update
&& apt-get install -y --no-install-recommends
ca-certificates
fonts-liberation
fonts-ipafont-gothic
fonts-wqy-zenhei
fonts-thai-tlwg
fonts-kacst
fonts-freefont-ttf
locales
&& sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen
&& locale-gen
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["node", "capture.js"]Choose packages for the scripts your page actually uses; installing every language package increases image size. System-wide installation is usually the most reproducible choice for pages that rely on normal CSS font-family names. Verify the image after installation rather than assuming the package was included.
Bundled application fonts
You can ship licensed font files with the application instead of installing packages globally. This makes the app self-contained, but you must have redistribution rights and ensure the browser can reach the files. A valid declaration should identify each requested weight and style:
@font-face {
font-family: "Acme Sans";
src: url("/fonts/acme-sans-regular.woff2") format("woff2");
font-weight: 400;
font-style: normal;
font-display: block;
}
@font-face {
font-family: "Acme Sans";
src: url("/fonts/acme-sans-600.woff2") format("woff2");
font-weight: 600;
font-style: normal;
font-display: block;
}
@font-face {
font-family: "Acme Sans";
src: url("/fonts/acme-sans-italic.woff2") format("woff2");
font-weight: 400;
font-style: italic;
font-display: block;
}If CSS requests 500, 600, 700, italic, or a variable-font axis that you did not provide, Chrome may synthesize a style or fall back. Supply the exact files and descriptors, or change CSS to weights you have.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
Make Puppeteer wait for fonts before capture
The browser must be able to resolve the font URL from inside the runtime. Check DNS, authentication, certificates, CSP, and relative paths from the page origin. Then wait for the document’s font set before producing a PDF or image.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({headless: true});
const page = await browser.newPage();
await page.goto('https://example.com/report', {waitUntil: 'networkidle0'});
await page.evaluate(async () => {
await document.fonts.ready;
if (document.fonts.status !== 'loaded') throw new Error('Fonts did not load');
});
await page.pdf({path: 'report.pdf', printBackground: true});
await browser.close();For applications that load fonts after hydration, wait for a selector or an app-specific readiness flag as well. A fixed delay can mask races but is less reliable than an explicit condition. Inspect failed font requests in request logging and check the browser console for CORS or decode errors.
Keep Puppeteer and Chrome compatible
When installed normally, Puppeteer downloads a recent compatible Chrome for Testing build. If installation scripts were blocked (for example, with an ignored-scripts package install), the browser may be absent and launch will fail with a message such as “Could not find Chrome (ver. …)”. Allow the supported install step, run the documented browser installation command for your Puppeteer version, or point Puppeteer explicitly at a browser binary that matches the package.
Record both versions in CI logs. Do not mix an old Puppeteer with an unrelated system Chromium and expect identical font behavior. Pin your Node image, Puppeteer dependency, and browser installation strategy so rebuilds use the same inputs.
Rank #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.
Alpine requires separate validation
Alpine does not work out of the box for every Puppeteer/Chromium combination. Its musl-based userspace, package names, sandbox dependencies, and Chromium version must match the Puppeteer release. If fonts work in Debian but fail in Alpine, first reproduce with a supported Debian-based image. Move back to Alpine only after confirming compatible Chromium, dependencies, locale data, and font packages; otherwise the smaller image can cost more time than it saves.
Distinguish missing glyphs from Linux rendering differences
If every glyph is present but text width, kerning, or antialiasing differs from macOS, investigate Linux font hinting rather than installing more fonts. Compare a controlled capture with Chromium’s --font-render-hinting=none flag:
const browser = await puppeteer.launch({
headless: true,
args: ['--font-render-hinting=none']
});This flag is an issue-specific workaround, not a universal fix. Keep it only if it improves your target output, and record the Chromium version and platform because rendering can change between browser builds. Do not use it to hide a missing web-font request or a fallback face.
A practical decision checklist
| Symptom | Most likely cause | Action |
|---|---|---|
| Boxes or blank characters | Missing glyph coverage | Install a package covering that script and rerun the specimen. |
| Correct family but wrong bold/italic | Requested weight or style is absent | Add matching @font-face files/descriptors or adjust CSS. |
| Web font never appears | Unreachable URL, CORS/CSP, or capture race | Inspect requests, fix reachability, then await document.fonts.ready. |
| “Could not find Chrome” | Blocked Puppeteer browser install or mismatched executable | Install the compatible Chrome for Testing build or configure a matching binary. |
| Only Alpine fails | Unsupported dependency/browser combination | Use a supported Debian image or align Alpine Chromium and Puppeteer versions. |
| Glyphs exist but spacing differs | Linux hinting/antialiasing | Compare with --font-render-hinting=none and pin the browser version. |
Troubleshoot common failures
Fonts are installed but Chrome cannot see them
Confirm the package is in the final image stage, not only a discarded build stage. Rebuild without a stale layer, check locale environment variables inside the running container, and verify the font file path or family name used by CSS. If you bundle fonts, serve them from the same origin or configure the required cross-origin headers.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →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
PDFs differ from screenshots
Both APIs use the page’s loaded fonts, but print CSS can select different families, weights, or visibility rules. Test with print media settings, include printBackground: true when needed, and wait for fonts after applying the same media type used for the PDF.
Intermittent fallback in CI
Parallel jobs, cold caches, and delayed font requests can expose a race. Wait for network idle plus document.fonts.ready, avoid deleting the font cache during a run, and capture browser console/request errors on failure. A deterministic container is preferable to relying on whatever fonts a shared runner happens to provide.
Emoji remain different
Emoji are often supplied by platform-specific color fonts. Install an emoji-capable font permitted by your distribution and accept that glyph design can vary by operating system; do not treat a different but valid emoji design as a Puppeteer font-load failure.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server for developers. One request returns PNG, JPEG, WebP, or PDF, with options for full-page lazy-image loading, CSS-selector elements, device and retina settings, custom CSS/JavaScript, waits, request blocking, headers/cookies, timezone and geolocation, resizing, caching, signed links, async webhooks, bulk capture, and more.
Recommended Free Tools
Best 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 same URL-based call when you do not want to maintain a Chrome image:
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 documentation for output and option names. Before capture it accepts the cookie/consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and whether it was billed. Its MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up free.
Cost, reliability, and reproducibility notes
- System fonts increase image size but make CI output predictable; bundled fonts reduce host assumptions but add licensing and asset-delivery work.
- Waiting for real readiness conditions avoids flaky captures and prevents PDFs with fallback text, although network-idle waits can be unsuitable for pages with long-lived connections.
- Pin the base image, locale, font packages, Puppeteer version, and browser version. Keep a multilingual specimen as a regression test when upgrading any of them.
- There is no general success-rate benchmark for these fixes; results depend on scripts, fonts, browser builds, and deployment images.
Frequently Asked Questions
Should I install fonts on the host or in Docker?
Install them in the same runtime image that launches Chrome. Host fonts are not inherited by an isolated container.
Can a fallback font be acceptable?
Yes, if its glyph coverage and metrics meet your product requirements. Make that choice explicit and test the resulting line breaks rather than assuming the intended family loaded.
Why does a variable font still look wrong?
Check that the declared variable axes and requested CSS ranges are supported by the actual file, and that the browser can fetch that file before capture.
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.
