To make Puppeteer PDFs from Windows and CentOS more alike, align the actual Chromium build and Puppeteer version, use identical page inputs, select the same media type, set every PDF layout option explicitly, and verify that CentOS has the exact fonts your document uses. Then compare the outputs one variable at a time. Identical output is not guaranteed across operating systems or browser builds; treat any remaining mismatch—especially font metrics—as a diagnostic problem, not something one launch flag is certain to fix.
Why the PDFs differ
Page.pdf() renders using print CSS by default, not the screen appearance you see in a browser window. Print styles, print color handling, paper settings, and font availability can all alter the result. Puppeteer’s documentation explains that screen media must be selected explicitly with page.emulateMediaType('screen') before generating the PDF if that is the intended output. Puppeteer Page.pdf() documentation
Fonts are a frequent source of layout drift. If CentOS cannot load a requested family or weight, Chromium may substitute another font with different glyph widths. That can change line wrapping, element heights, and page breaks even when the HTML and CSS match. The relevant comparison is not just “Windows versus Linux”: it includes the OS release, browser build, content and assets, font files and glyph coverage, CSS media, and PDF settings.
Align the inputs and runtime first
- Record what actually runs. Capture the Puppeteer version, the Chromium executable path and version, OS release and architecture, and all launch arguments on both machines. The npm package version alone does not prove that both processes use the same browser build.
- Make the page inputs identical. Compare the exact HTML, CSS, data, viewport assumptions, and loaded assets. Ensure both runs finish loading the same images and web fonts before PDF generation.
- Choose the intended media. For print output, leave the default print media behavior in place and ensure your print stylesheet is intentional. For screen-style output, call
await page.emulateMediaType('screen')beforepage.pdf(). Do not compare a print-media PDF on one machine with screen-media output on the other. - Set PDF options explicitly. Use matching paper dimensions or format, margins, scale, orientation, background printing, and CSS page-size behavior. Avoid relying on defaults that may not match your document’s assumptions.
Use identical PDF settings
Puppeteer’s PDF API documents options for paper format or dimensions, margins, scale, landscape orientation, background graphics, and whether CSS @page sizing takes priority. The documented defaults include Letter paper, printBackground: false, and preferCSSPageSize: false; when the latter is false, content is scaled to fit the selected paper size. Set these values deliberately in both environments. Puppeteer PDFOptions documentation
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
const pdfOptions = {
format: 'A4',
landscape: false,
printBackground: true,
preferCSSPageSize: true,
scale: 1,
margin: {
top: '12mm',
right: '12mm',
bottom: '12mm',
left: '12mm',
},
};
await page.pdf({ path: 'output.pdf', ...pdfOptions });This is an example configuration, not a requirement to use A4 or these margins. Choose the values your document needs, then keep them the same on both machines. If your CSS defines @page dimensions, decide whether those dimensions or the API paper size should govern and set preferCSSPageSize accordingly.
For color comparisons, note that Puppeteer modifies colors for printing by default. If exact CSS colors are required, the Puppeteer page documentation points to -webkit-print-color-adjust; use it in the relevant print CSS and keep that CSS identical between environments. Puppeteer Page.pdf() documentation
Check CentOS libraries and the document’s fonts
First ensure Chromium can start with its required shared libraries. Puppeteer’s troubleshooting guide suggests checking unresolved Chrome libraries with ldd chrome | grep not. The executable path may differ, so run the command against the Chromium binary actually used by your process. The guide lists CentOS dependencies that include Pango libraries, X font packages, and ipa-gothic-fonts. Package names and availability can vary by CentOS release, and those dependencies do not establish that every font your page needs is installed. Puppeteer troubleshooting guide
- Inspect the CSS font stack, including requested weights and styles, rather than checking only the first family name.
- Verify the expected font files are installed and discoverable by the running environment.
- For web fonts, verify that the request succeeds and the intended face is actually available to the document.
- For non-Latin text, check glyph coverage as well as the family name; a font can load but still lack some characters.
Keep Puppeteer’s font wait enabled unless you have a specific reason to disable it. The current PDF options describe waitForFonts as true by default and wait for document.fonts.ready. Puppeteer’s PDF guide also says that Page.pdf() waits for fonts by default. If you are generating from a background page and font readiness does not resolve, the API documentation notes that bringing the page to the foreground may be necessary. Waiting does not repair a failed font request or install a missing system font; confirm that the desired fonts loaded successfully. Puppeteer PDFOptions documentation · Puppeteer PDF generation guide
Crashes, 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 minutePC 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 & 11Compare outputs in a controlled sequence
- Save both PDFs along with the exact HTML, CSS, data, asset versions, runtime details, and PDF options used to create them.
- Check page dimensions, margins, and scaling first. These can make every element appear displaced even when text metrics match.
- Compare fonts and glyph selection, then text widths and line wrapping. A width change often explains downstream differences in block height and page breaks.
- Inspect page breaks and element geometry after confirming typography and page settings.
- Compare print colors and backgrounds separately from layout.
- Change one factor at a time and regenerate both PDFs. This helps distinguish an environment difference from an input or configuration change.
There is no evidence-based prevalence figure for how often these cross-platform differences occur. A Puppeteer issue discussion reports differences in font widths across Windows and Linux and notes that results can vary with the font, OS, browser version, and content. Treat that discussion as a concrete example of the variables involved, not as a guarantee that every pair of systems will differ in the same way. Puppeteer issue #2410
Test font hinting only as a targeted experiment
If the remaining discrepancy is specifically font metrics, you can test Chromium’s --font-render-hinting=medium launch argument as an isolated experiment:
const browser = await puppeteer.launch({
args: ['--font-render-hinting=medium'],
});A Puppeteer contributor suggested this flag in a 2019 comment in the issue discussion for one reported rendering case. It is not a current API guarantee or a universal cross-version fix. Compare it on the exact target systems, keep all other variables fixed, and remove it if it does not improve the result. Puppeteer issue #2410
Keep the Linux sandbox enabled
Disabling Chromium’s sandbox is not a PDF-alignment technique. Puppeteer’s troubleshooting guide strongly discourages running without a sandbox. Keep it enabled where possible and address launch dependencies or environment configuration instead of weakening browser isolation to chase visual consistency. Puppeteer troubleshooting guide
Recommended Free Tools
Troubleshooting common symptoms
| Symptom | Likely cause to check | Next action |
|---|---|---|
| Text is wider or wraps differently on CentOS | Font substitution, missing weight, or differing browser build | Confirm the exact font files and weights are installed and loaded; compare Chromium versions and then inspect glyph coverage. |
| Content shifts or pages break at different points | Different font metrics, paper size, margins, scale, or CSS page-size handling | Set PDF options explicitly and compare layout only after font readiness and page dimensions match. |
| Colors or backgrounds differ | Print color adjustment or background printing settings | Match printBackground and apply the intended -webkit-print-color-adjust rule in shared print CSS. |
| Custom web fonts appear absent or intermittent | Failed or incomplete font loading | Inspect font requests and document font readiness; retain waitForFonts: true unless there is a specific reason not to. |
| Chromium will not launch on CentOS | Missing shared libraries or other required browser dependencies | Run ldd against the actual executable and check the Puppeteer dependency guide for the CentOS release in use. |
| A hinting flag changes nothing or makes results worse | The mismatch is not the reported font-hinting case, or behavior differs by build | Remove the flag and continue isolating fonts, versions, inputs, and PDF settings. |
Or skip the browser setup
If your goal is a website screenshot or PDF rather than reproducing a local Puppeteer environment, ScreenshotNeo offers a one-request screenshot API and an MCP server. A screenshot API does not make Windows and CentOS render identically; it gives you a managed capture path instead of maintaining the browser setup yourself.
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 and formats. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. AI agents can use its MCP server tools to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan to try 1,000 screenshots a month with no card.
Frequently Asked Questions
Does matching the Puppeteer package version guarantee identical PDFs?
No. The Chromium build, operating system, fonts, page content, and PDF settings also affect rendering.
Should I use `–font-render-hinting=medium` on every CentOS deployment?
No. It was suggested for one case in a 2019 issue comment; test it only when investigating font-metric differences.
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.
