lifestyle.projectdiaspora.org

How to Migrate from PuppeteerSharp to IronPDF

Syndication Cloud
PuppeteerSharp to IronPDFPhoto from Pexels

Originally Posted On: https://ironpdf.com/blog/migration-guides/migrate-from-puppeteersharp-to-ironpdf/

 

Migrating from PuppeteerSharp to IronPDF transforms your PDF generation workflow from a browser automation tool with 300MB+ dependencies to a purpose-built PDF library with automatic memory management. This guide provides a complete, step-by-step migration path that eliminates Chromium downloads, solves memory leak issues, and provides comprehensive PDF manipulation capabilities.

Why Migrate from PuppeteerSharp to IronPDF

Understanding PuppeteerSharp

PuppeteerSharp is a .NET port of Google’s Puppeteer, bringing browser automation capabilities to C#. It generates PDFs using Chrome’s built-in print-to-PDF functionality—the same as hitting Ctrl+P in a browser. This produces print-ready output optimized for paper, which differs from what you see on screen.

PuppeteerSharp was designed for web testing and scraping, not document generation. While capable, using PuppeteerSharp for PDF generation creates significant production challenges.

The Browser Automation Problem

PuppeteerSharp was designed for browser automation, not document generation. This creates fundamental issues when using it for PDFs:

  1. 300MB+ Chromium downloads required before first use. A significant downside of PuppeteerSharp is its hefty deployment size, mainly due to the Chromium binary it bundles. This substantial size can bloat Docker images and cause cold start issues in serverless environments.
  2. Memory leaks under load requiring manual browser recycling. Under heavy load, PuppeteerSharp is known to experience memory leaks. The accumulation of memory by browser instances necessitates manual intervention for process management and recycling.
  3. Complex async patterns with browser lifecycle management.
  4. Print-to-PDF output (equivalent to Ctrl+P, not screen capture). Layouts may reflow, backgrounds may be omitted by default, and the output is paginated for printing rather than matching the browser viewport.
  5. No PDF/A or PDF/UA support for compliance requirements. PuppeteerSharp cannot produce PDF/A (archival) or PDF/UA (accessibility) compliant documents.
  6. No PDF manipulation – generation only, no merge/split/edit. While PuppeteerSharp is efficient at generating PDFs, it lacks capabilities for further manipulation such as merging, splitting, securing, or editing PDFs.

PuppeteerSharp vs IronPDF Comparison

Aspect PuppeteerSharp IronPDF
Primary Purpose Browser automation PDF generation
Chromium Dependency 300MB+ separate download Built-in optimized engine
API Complexity Async browser/page lifecycle Synchronous one-liners
Initialization BrowserFetcher.DownloadAsync() + LaunchAsync new ChromePdfRenderer()
Memory Management Manual browser recycling required Automatic
Memory Under Load 500MB+ with leaks ~50MB stable
Cold Start 45+ seconds ~20 seconds
PDF/A Support Not available Supported
PDF/UA Accessibility Not available Supported
PDF Editing Not available Merge, split, stamp, edit
Digital Signatures Not available Supported
Thread Safety Limited Full
Professional Support Community Commercial with SLA

Platform Support

| Library | .NET Framework 4.7.2 | .NET Core 3.1 | .NET 6-8 | .NET 10 | | ——— | :—: | :—: | :—: | :—: || IronPDF | Full | Full | Full | Full || PuppeteerSharp | Limited | Full | Full | Pending | IronPDF’s extensive support across .NET platforms ensures developers can leverage it in various environments without encountering compatibility issues, providing a flexible choice for modern .NET applications through 2025 and 2026.

Before You Start

Prerequisites

  1. .NET Environment: .NET Framework 4.6.2+ or .NET Core 3.1+ / .NET 5/6/7/8/9+
  2. NuGet Access: Ability to install NuGet packages
  3. IronPDF License: Obtain your license key from ironpdf.com

NuGet Package Changes

  1. # Remove PuppeteerSharp
  2. dotnet remove package PuppeteerSharp
  4. # Remove downloaded Chromium binaries (~300MB recovered)
  5. # Delete the .local-chromium folder
  7. # Add IronPDF
  8. dotnet add package IronPdf
SHELL

No BrowserFetcher.DownloadAsync() required with IronPDF – the rendering engine is bundled automatically.

License Configuration

  1. // Add at application startup
  2. IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

Complete API Reference

Namespace Changes

  1. // Before: PuppeteerSharp
  2. using PuppeteerSharp;
  3. using PuppeteerSharp.Media;
  4. using System.Threading.Tasks;
  6. // After: IronPDF
  7. using IronPdf;
  8. using IronPdf.Rendering;

Core API Mappings

PuppeteerSharp API IronPDF API Notes
new BrowserFetcher().DownloadAsync() Not needed No browser download
Puppeteer.LaunchAsync(options) Not needed No browser management
browser.NewPageAsync() Not needed No page context
page.GoToAsync(url) renderer.RenderUrlAsPdf(url) Direct rendering
page.SetContentAsync(html) renderer.RenderHtmlAsPdf(html) Direct rendering
page.PdfAsync(path) pdf.SaveAs(path) After rendering
await page.CloseAsync() Not needed Automatic cleanup
await browser.CloseAsync() Not needed Automatic cleanup
PdfOptions.Format RenderingOptions.PaperSize Paper size
PdfOptions.Landscape RenderingOptions.PaperOrientation Orientation
PdfOptions.MarginOptions RenderingOptions.MarginTop/Bottom/Left/Right Individual margins
PdfOptions.PrintBackground RenderingOptions.PrintHtmlBackgrounds Background printing
PdfOptions.HeaderTemplate RenderingOptions.HtmlHeader HTML headers
PdfOptions.FooterTemplate RenderingOptions.HtmlFooter HTML footers
page.WaitForSelectorAsync() RenderingOptions.WaitFor.HtmlElementId Wait for element

Code Migration Examples

Example 1: Basic HTML to PDF Conversion

Before (PuppeteerSharp):

  1. // NuGet: Install-Package PuppeteerSharp
  2. using PuppeteerSharp;
  3. using System.Threading.Tasks;
  5. class Program
  6. {
  7. static async Task Main(string[] args)
  8. {
  9. var browserFetcher = new BrowserFetcher();
  10. await browserFetcher.DownloadAsync();
  12. await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
  13. {
  14. Headless = true
  15. });
  17. await using var page = await browser.NewPageAsync();
  18. await page.SetContentAsync("<h1>Hello World</h1><p>This is a PDF document.</p>");
  19. await page.PdfAsync("output.pdf");
  20. }
  21. }

After (IronPDF):

  1. // NuGet: Install-Package IronPdf
  2. using IronPdf;
  4. class Program
  5. {
  6. static void Main(string[] args)
  7. {
  8. var renderer = new ChromePdfRenderer();
  9. var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1><p>This is a PDF document.</p>");
  10. pdf.SaveAs("output.pdf");
  11. }
  12. }

This example demonstrates the fundamental architectural difference. PuppeteerSharp requires six async operations: BrowserFetcher.DownloadAsync() (300MB+ Chromium download), Puppeteer.LaunchAsync(), browser.NewPageAsync(), page.SetContentAsync(), and page.PdfAsync(), plus proper disposal with await using.

IronPDF eliminates all this complexity: create a ChromePdfRenderer, call RenderHtmlAsPdf(), and SaveAs(). No async patterns, no browser lifecycle, no Chromium downloads. IronPDF’s approach offers cleaner syntax and better integration with modern .NET applications. See the HTML to PDF documentation for comprehensive examples.

Example 2: URL to PDF Conversion

Before (PuppeteerSharp):

  1. // NuGet: Install-Package PuppeteerSharp
  2. using PuppeteerSharp;
  3. using System.Threading.Tasks;
  5. class Program
  6. {
  7. static async Task Main(string[] args)
  8. {
  9. var browserFetcher = new BrowserFetcher();
  10. await browserFetcher.DownloadAsync();
  12. await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
  13. {
  14. Headless = true
  15. });
  17. await using var page = await browser.NewPageAsync();
  18. await page.GoToAsync("https://www.example.com");
  19. await page.PdfAsync("webpage.pdf");
  20. }
  21. }

After (IronPDF):

  1. // NuGet: Install-Package IronPdf
  2. using IronPdf;
  4. class Program
  5. {
  6. static void Main(string[] args)
  7. {
  8. var renderer = new ChromePdfRenderer();
  9. var pdf = renderer.RenderUrlAsPdf("https://www.example.com");
  10. pdf.SaveAs("webpage.pdf");
  11. }
  12. }

PuppeteerSharp uses GoToAsync() to navigate to a URL followed by PdfAsync(). IronPDF provides a single RenderUrlAsPdf() method that handles navigation and PDF generation in one call. Learn more in our tutorials.

Example 3: Custom Page Settings with Margins

Before (PuppeteerSharp):

  1. // NuGet: Install-Package PuppeteerSharp
  2. using PuppeteerSharp;
  3. using PuppeteerSharp.Media;
  4. using System.Threading.Tasks;
  6. class Program
  7. {
  8. static async Task Main(string[] args)
  9. {
  10. var browserFetcher = new BrowserFetcher();
  11. await browserFetcher.DownloadAsync();
  13. await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
  14. {
  15. Headless = true
  16. });
  18. await using var page = await browser.NewPageAsync();
  19. await page.SetContentAsync("<h1>Custom PDF</h1><p>With landscape orientation and margins.</p>");
  21. await page.PdfAsync("custom.pdf", new PdfOptions
  22. {
  23. Format = PaperFormat.A4,
  24. Landscape = true,
  25. MarginOptions = new MarginOptions
  26. {
  27. Top = "20mm",
  28. Bottom = "20mm",
  29. Left = "20mm",
  30. Right = "20mm"
  31. }
  32. });
  33. }
  34. }

After (IronPDF):

  1. // NuGet: Install-Package IronPdf
  2. using IronPdf;
  3. using IronPdf.Rendering;
  5. class Program
  6. {
  7. static void Main(string[] args)
  8. {
  9. var renderer = new ChromePdfRenderer();
  10. renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;
  11. renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape;
  12. renderer.RenderingOptions.MarginTop = 20;
  13. renderer.RenderingOptions.MarginBottom = 20;
  14. renderer.RenderingOptions.MarginLeft = 20;
  15. renderer.RenderingOptions.MarginRight = 20;
  17. var pdf = renderer.RenderHtmlAsPdf("<h1>Custom PDF</h1><p>With landscape orientation and margins.</p>");
  18. pdf.SaveAs("custom.pdf");
  19. }
  20. }

This example shows how PDF options map between the two libraries. PuppeteerSharp uses PdfOptions with Format, Landscape, and MarginOptions containing string values ("20mm"). IronPDF uses RenderingOptions properties with direct paper size enums, orientation enums, and numeric margin values in millimeters.

Key mappings:

  • Format = PaperFormat.A4 → PaperSize = PdfPaperSize.A4
  • Landscape = true → PaperOrientation = PdfPaperOrientation.Landscape
  • MarginOptions.Top = "20mm" → MarginTop = 20 (numeric millimeters)

The Memory Leak Problem

PuppeteerSharp is notorious for memory accumulation under sustained load:

  1. // ❌ PuppeteerSharp - Memory grows with each operation
  2. // Requires explicit browser recycling every N operations
  3. for (int i = 0; i < 1000; i++)
  4. {
  5. var page = await browser.NewPageAsync();
  6. await page.SetContentAsync($"<h1>Document {i}</h1>");
  7. await page.PdfAsync($"doc_{i}.pdf");
  8. await page.CloseAsync(); // Memory still accumulates!
  9. }
  10. // Must periodically: await browser.CloseAsync(); and re-launch
  12. // ✅ IronPDF - Stable memory, reuse renderer
  13. var renderer = new ChromePdfRenderer();
  14. for (int i = 0; i < 1000; i++)
  15. {
  16. var pdf = renderer.RenderHtmlAsPdf($"<h1>Document {i}</h1>");
  17. pdf.SaveAs($"doc_{i}.pdf");
  18. // Memory managed automatically
  19. }

IronPDF eliminates the need for browser pooling infrastructure that PuppeteerSharp requires:

  1. // Before (PuppeteerSharp - delete entire class)
  2. public class PuppeteerBrowserPool
  3. {
  4. private readonly ConcurrentBag<IBrowser> _browsers;
  5. private readonly SemaphoreSlim _semaphore;
  6. private int _operationCount;
  7. // ... recycling logic ...
  8. }
  10. // After (IronPDF - simple reuse)
  11. public class PdfService
  12. {
  13. private readonly ChromePdfRenderer _renderer = new();
  15. public byte[] Generate(string html)
  16. {
  17. return _renderer.RenderHtmlAsPdf(html).BinaryData;
  18. }
  19. }

Critical Migration Notes

Async to Sync Conversion

PuppeteerSharp requires async/await throughout; IronPDF supports synchronous operations:

  1. // PuppeteerSharp: Async required
  2. public async Task<byte[]> GeneratePdfAsync(string html)
  3. {
  4. await new BrowserFetcher().DownloadAsync();
  5. await using var browser = await Puppeteer.LaunchAsync(...);
  6. await using var page = await browser.NewPageAsync();
  7. await page.SetContentAsync(html);
  8. return await page.PdfDataAsync();
  9. }
  11. // IronPDF: Sync default
  12. public byte[] GeneratePdf(string html)
  13. {
  14. var renderer = new ChromePdfRenderer();
  15. return renderer.RenderHtmlAsPdf(html).BinaryData;
  16. }
  18. // Or async when needed
  19. public async Task<byte[]> GeneratePdfAsync(string html)
  20. {
  21. var renderer = new ChromePdfRenderer();
  22. var pdf = await renderer.RenderHtmlAsPdfAsync(html);
  23. return pdf.BinaryData;
  24. }

Margin Unit Conversion

PuppeteerSharp uses string units; IronPDF uses numeric millimeters:

  1. // PuppeteerSharp - string units
  2. MarginOptions = new MarginOptions
  3. {
  4. Top = "1in", // 25.4mm
  5. Bottom = "0.75in", // 19mm
  6. Left = "1cm", // 10mm
  7. Right = "20px" // ~7.5mm at 96dpi
  8. }
  10. // IronPDF - numeric millimeters
  11. renderer.RenderingOptions.MarginTop = 25; // mm
  12. renderer.RenderingOptions.MarginBottom = 19;
  13. renderer.RenderingOptions.MarginLeft = 10;
  14. renderer.RenderingOptions.MarginRight = 8;
PuppeteerSharp Class IronPDF Placeholder
<span class='pageNumber'> {page}
<span class='totalPages'> {total-pages}
<span class='date'> {date}
<span class='title'> {html-title}

New Capabilities After Migration

After migrating to IronPDF, you gain capabilities that PuppeteerSharp cannot provide:

PDF Merging

  1. var pdf1 = renderer.RenderHtmlAsPdf(html1);
  2. var pdf2 = renderer.RenderHtmlAsPdf(html2);
  3. var merged = PdfDocument.Merge(pdf1, pdf2);
  4. merged.SaveAs("merged.pdf");

Watermarks

  1. var watermark = new TextStamper
  2. {
  3. Text = "CONFIDENTIAL",
  4. FontSize = 48,
  5. Opacity = 30,
  6. Rotation = -45
  7. };
  8. pdf.ApplyStamp(watermark);

Password Protection

  1. pdf.SecuritySettings.OwnerPassword = "admin";
  2. pdf.SecuritySettings.UserPassword = "readonly";
  3. pdf.SecuritySettings.AllowUserCopyPasteContent = false;

Digital Signatures

  1. var signature = new PdfSignature("certificate.pfx", "password");
  2. pdf.Sign(signature);

PDF/A Compliance

  1. pdf.SaveAsPdfA("archive.pdf", PdfAVersions.PdfA3b);

Performance Comparison Summary

Metric PuppeteerSharp IronPDF Improvement
First PDF (Cold Start) 45s+ ~20s 55%+ faster
Subsequent PDFs Variable Consistent Predictable
Memory Usage 500MB+ (grows) ~50MB (stable) 90% less memory
Disk Space (Chromium) 300MB+ 0 Eliminate downloads
Browser Download Required Not needed Zero setup
Thread Safety Limited Full Reliable concurrency
PDF Generation Time 45s 20s 55% faster

Migration Checklist

Pre-Migration

  • Identify all PuppeteerSharp usages in codebase
  • Document margin values (convert strings to millimeters)
  • Note header/footer placeholder syntax for conversion
  • Delete browser pooling/recycling infrastructure
  • Obtain IronPDF license key from ironpdf.com

Package Changes

  • Remove PuppeteerSharp NuGet package
  • Delete .local-chromium folder to reclaim ~300MB disk space
  • Install IronPdf NuGet package: dotnet add package IronPdf

Code Changes

  • Update namespace imports
  • Remove BrowserFetcher.DownloadAsync() calls
  • Remove Puppeteer.LaunchAsync() and browser management
  • Replace page.SetContentAsync() + page.PdfAsync() with RenderHtmlAsPdf()
  • Replace page.GoToAsync() + page.PdfAsync() with RenderUrlAsPdf()
  • Convert margin strings to millimeter values
  • Convert header/footer placeholder syntax
  • Remove all browser/page disposal code
  • Delete browser pooling infrastructure
  • Add license initialization at application startup

Post-Migration

  • Visual comparison of PDF output
  • Load test for memory stability (should stay stable without recycling)
  • Verify header/footer rendering with page numbers
  • Add new capabilities (security, watermarks, merging) as needed

 

More Press Releases