The simplest supported workflow is four steps: launch PuppeteerSharp in Chrome headless mode, create a page, navigate to a URL (or set HTML), then await PdfAsync("output.pdf"). PuppeteerSharp resolves the supplied path with GetFullPath, uses print CSS media by default, and writes the generated PDF directly to disk.
Prerequisites and the supported PDF engine
Add PuppeteerSharp to your .NET project and make sure a compatible Chrome/Chromium executable is available for the launch configuration you deploy. The PuppeteerSharp Page API documents PDF generation as supported only in Chrome headless mode. Package versions and target-framework compatibility can change, so check the NuGet package details and your project target framework when you install or upgrade.
PDF output uses print CSS media by default. That means rules inside @media print and print-oriented layout behavior are applied. If the page must be rendered as it appears on screen, explicitly emulate screen media before creating the PDF.
Save a web page directly to a file
This is the minimal complete flow for a URL:
using PuppeteerSharp;
using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
{
Headless = true
});
using var page = await browser.NewPageAsync();
await page.GoToAsync("https://example.com");
await page.PdfAsync("output.pdf");PdfAsync(string file) accepts the destination path and returns after PuppeteerSharp has generated the document. A relative path is resolved to its full path by the API. Use an absolute path when the process working directory may differ between local development, a service, a container, and a scheduled job.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
- BEST FOR SMALL BUSINESSES – Engineered for extraordinary productivity, the Brother DCP-L2640DW Monochrome (Black & White) 3-in-1 combines laser printer, scanner, copier in one compact footprint and delivers high-quality black & white prints
- FAST PRINTER WITH EFFICIENT SCANNING – Produces documents quickly with print speeds up to 36 ppm(2) and scan speeds up to 23.6/7.9 ipm(3) (black/color). A 50-page auto document feeder(4) allows for convenient, time saving multi-page scanning and copying
- FLEXIBLE CONNECTION OPTIONS – Easily navigate the changing demands of your business with secure multi-device connectivity via built-in dual-band wireless (2.4GHz / 5GHz) and Ethernet. Or connect locally to a single computer via USB interface
- BROTHER MOBILE CONNECT APP – Print, scan, and manage your wireless printer anytime, from almost anywhere from your mobile device. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(5)
- CHOOSE BROTHER GENUINE TONER – When it’s time to replace your toner, be sure to choose Brother Genuine TN830 or TN830XL replacement toner. And with Refresh EZ Print Subscription Service, you’ll never worry about running out of toner again and you’ll enjoy savings of up to 50%(6) on Brother Genuine Toner. Get started with Refresh today with a Free Trial(1)
Navigate reliably before printing
Choose a navigation wait condition that matches the site. A page that renders its final content after JavaScript may need an appropriate WaitUntil setting or an explicit wait for a selector before calling PdfAsync. The PDF call captures the page state that exists at that moment; it does not replace application-specific readiness checks.
await page.GoToAsync(
"https://example.com/report",
new NavigationOptions
{
WaitUntil = new[] { WaitUntilNavigation.Networkidle0 }
});
await page.PdfAsync("reports/report.pdf");For pages whose data appears only after a known element is present, wait for that selector using the page-wait API available in your installed PuppeteerSharp version, then generate the PDF.
Generate a PDF from supplied HTML
When your application owns the markup, use SetContentAsync instead of navigation:
using PuppeteerSharp;
var html = """
Invoice
Invoice 1042
Prepared for the customer.
Total: $125.00
""";
using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
{
Headless = true
});
using var page = await browser.NewPageAsync();
await page.SetContentAsync(html);
await page.PdfAsync("invoice-1042.pdf");Inline or linked styles, fonts, images, and scripts must be available to the page at print time. If those resources are loaded remotely, account for authentication, network failures, and delayed rendering before printing.
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 & 11Choose file, byte-array, or stream output
PuppeteerSharp exposes three output forms. They are API alternatives, not a documented performance ranking.
Rank #2
- BEST FOR HOMES & HOME OFFICES – Engineered for consistent, premium print quality, the Brother HL-L2405W Monochrome (Black & White) Laser Printer delivers sharp, crisp prints at an affordable price. Prints one-sided documents at speeds up to 30ppm(2)
- COMPACT, CONNECTED PRINTER – Flexible connection options make this an ideal printer for home use and at-home offices. Securely connect to multiple devices with built-in dual-band wireless (2.4GHz/5GHz) or locally to a single computer via USB interface
- BROTHER MOBILE CONNECT APP – Manage your printer remotely and print from your mobile device anytime, from almost anywhere. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(3)
- VERSATILE PAPER HANDLING – Enjoy seamless, reliable everyday printing with the 250-sheet paper tray(4) and a manual feed slot that enables printing on envelopes and specialty pape
- BROTHER IS AT YOUR SIDE – Backed by Brother with a 1-year limited warranty and free online, call, or live chat support for the life of your printer
| Method | Use it when | Typical destination |
|---|---|---|
PdfAsync(path) |
You want PuppeteerSharp to persist the result directly. | A local or mounted filesystem path. |
PdfDataAsync(options) |
Your code needs the complete PDF as bytes. | An HTTP response body, object-storage upload, database, or transformation step. |
PdfStreamAsync(options) |
The surrounding API is stream-oriented. | A response stream or another streaming pipeline. |
Return bytes from an ASP.NET Core endpoint
using PuppeteerSharp;
app.MapGet("/invoice/{id}.pdf", async (string id) =>
{
using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
{
Headless = true
});
using var page = await browser.NewPageAsync();
await page.GoToAsync($"https://example.com/invoices/{id}");
var pdf = await page.PdfDataAsync(new PdfOptions
{
Format = PaperFormat.A4,
PrintBackground = true
});
return Results.File(pdf, "application/pdf", $"invoice-{id}.pdf");
});Use the stream method when you specifically need a stream; otherwise, the path or byte-array methods usually make ownership and response handling clearer.
Control paper, margins, media, and print layout
Pass a PdfOptions object to any corresponding PDF method when the defaults are not sufficient.
var options = new PdfOptions
{
Format = PaperFormat.A4,
Landscape = false,
PrintBackground = true,
DisplayHeaderFooter = true,
HeaderTemplate = "<div style='font-size:8px;width:100%;text-align:center'>Report</div>",
FooterTemplate = "<div style='font-size:8px;width:100%;text-align:center'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>",
MarginOptions = new MarginOptions
{
Top = "18mm",
Right = "14mm",
Bottom = "18mm",
Left = "14mm"
},
PreferCSSPageSize = true,
WaitForFonts = true
};
await page.PdfAsync("report.pdf", options);PdfOptions covers paper formats or custom dimensions, orientation, margins, page ranges, header and footer templates, background graphics, scaling, and whether CSS @page size takes priority. WaitForFonts is documented as enabled by default. Set PrintBackground when colored panels, chart fills, or background images are part of the document.
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 errorsUse screen media instead of print media
await page.EmulateMediaTypeAsync(MediaType.Screen);
await page.PdfAsync("screen-styled.pdf", new PdfOptions
{
Format = PaperFormat.Letter,
PrintBackground = true
});Call the emulation method before PDF generation. Otherwise, the documented default remains print media.
Tagged PDFs
The Tagged option requests a tagged, accessibility-oriented PDF. The API documentation notes that this currently works only in old headless mode. Treat that as a version-sensitive caveat: verify behavior with the Chromium and PuppeteerSharp versions you actually deploy rather than assuming every headless configuration supports it.
Rank #3
- FAST PRINT SPEEDS: Print up to 19 pages per minute.
- COMPACT DESIGN: Space-saving, compact design fits anywhere in your home, school or small office.
- WIRELESS CONNECTIVITY: Print from almost anywhere in your workspace using your compatible mobile device.
- PAPER CAPACITY: Up to 150 sheets.
- SUSTAINABILITY: Uses less than 2 watts in Energy Saver mode.
Lifecycle, cleanup, and deployment patterns
- Launch one browser process with
Headless = true. - Create a new page for the document.
- Navigate or call
SetContentAsync. - Wait for the content, fonts, and other required resources.
- Generate the file, bytes, or stream.
- Dispose the page and browser with
usingor an equivalenttry/finallyblock.
For a batch, reuse a browser process while creating isolated pages per document, then close the browser during graceful shutdown. Limit concurrency to what your host can sustain; each page can consume memory for its DOM, images, fonts, and scripts. In containers or restricted servers, verify that Chrome dependencies, sandbox policy, writable temporary directories, and the executable path are configured for that environment.
A remote-browser architecture is also possible: PuppeteerSharp can connect to a browser through a WebSocket endpoint. That demonstrates a deployment pattern, not a recommendation for a particular provider. Secure the endpoint and confirm that its Chromium version matches the features your PDF relies on.
Troubleshooting common failures
“Browser” or executable launch errors
Cause: Chrome is missing, inaccessible, or incompatible with the runtime. Fix: install or provision a supported Chrome/Chromium binary, configure its executable path when necessary, and test the same account and container image used in production.
The PDF is blank or missing late content
Cause: generation started before JavaScript, fonts, images, or data finished loading. Fix: use a suitable navigation wait, wait for a definitive content selector, and ensure required resources are reachable and authenticated.
Styles look wrong
Cause: print media is the default, or CSS backgrounds are disabled. Fix: add print-specific CSS, call EmulateMediaTypeAsync(MediaType.Screen) when screen styling is required, and set PrintBackground = true for backgrounds.
Rank #4
- BEST FOR HOME OFFICES & SMALL TEAMS – Engineered for consistent, premium print quality, the Brother HL-L2460DW Monochrome (Black & White) Laser Printer produces documents that are clear, crisp, and easy to review and share, all at an affordable price
- COMPACT, CONNECTED, EXCEPTIONALLY EFFICIENT– Connect with built-in dual-band wireless (2.4GHz/5GHz), Ethernet, or to a single computer via USB interface. Prints at speeds up to 36ppm(2), plus automatic duplex printing saves time and reduces paper waste
- BROTHER MOBILE CONNECT APP – Manage your wireless printer remotely and print from your mobile device anytime, from almost anywhere. Order Brother Genuine Supplies, track toner usage, and complete more work on-the-go(3)
- VERSATILE PAPER HANDLING – Tackle high-volume black & white printing with the 250-sheet capacity paper tray.(4) The manual feed slot enables printing on envelopes and specialty paper
- BROTHER IS AT YOUR SIDE – Backed by Brother with a 1-year limited warranty and free online, call, or live chat support for the life of your printer
Content is clipped or pages break badly
Cause: paper size, margins, scaling, or unbreakable elements do not match the design. Fix: set an explicit format or width, tune margins, use CSS break rules such as break-inside: avoid selectively, and test long tables and images.
Recommended Free Tools
Relative paths or assets fail with SetContentAsync
Cause: supplied HTML has no suitable base URL for relative resources. Fix: use absolute asset URLs, embed required assets, or provide a document structure and loading strategy appropriate to your application.
Output cannot be written
Cause: the destination directory does not exist or the process lacks permission. Fix: create the directory, use an absolute path, and grant the service account write access. For read-only filesystems, use PdfDataAsync or PdfStreamAsync and send the result elsewhere.
Or skip the browser setup
If your requirement is simply to obtain a clean website screenshot or PDF through an HTTP API, ScreenshotNeo provides a single-call alternative. Its cleanup step accepts consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. It also provides an MCP server for AI agents, with take_screenshot, get_page_info, and capture_pdf tools.
See the complete parameter reference in the ScreenshotNeo documentation. A PDF or image request can start with:
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
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}`);The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for the free ScreenshotNeo plan.
Best Value
- FROM AMERICA'S MOST TRUSTED PRINTER BRAND – Perfect for small teams printing professional-quality black & white documents and reports. Perfect for 1-3 people
- WORLD'S SMALLEST LASER IN ITS CLASS – Precision laser printing that fits anywhere
- FAST PRINT SPEEDS – Up to 21 black-and-white pages per minute single-sided
- WIRELESS WITH SELF-RESET – Helps you stay connected
- PRINT FROM ANY DEVICE – Wireless printing from any mobile device, PC or tablet. Works with Microsoft, Mac, AirPrint, Android, Chromebook and more
FAQ
Does PuppeteerSharp create PDFs in headed Chrome?
The documented PDF implementation is currently supported only in Chrome headless.
Can I use CSS to choose the paper size?
Yes. Use CSS @page rules and configure PreferCSSPageSize when CSS dimensions should take priority over the PDF option.
Which output method should a web API use?
Use PdfDataAsync for a byte-array response and PdfStreamAsync for a stream-oriented pipeline; use PdfAsync(path) when direct filesystem persistence is the requirement.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently Asked Questions
Does PuppeteerSharp create PDFs in headed Chrome?
The documented PDF implementation is currently supported only in Chrome headless.
Can I use CSS to choose the paper size?
Yes. Use CSS @page rules and configure PreferCSSPageSize when CSS dimensions should take priority over the PDF option.
Which output method should a web API use?
Use PdfDataAsync for a byte-array response and PdfStreamAsync for a stream-oriented pipeline; use PdfAsync(path) when direct filesystem persistence is the requirement.
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.
Free tools Windows power users keep installed
One-click scans. No signup required.
