Skip to footer content
MIGRATION GUIDES

How to Migrate from PuppeteerSharp to IronPDF in C#

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

AspectPuppeteerSharpIronPDF
Primary PurposeBrowser automationPDF generation
Chromium Dependency300MB+ separate downloadBuilt-in optimized engine
API ComplexityAsync browser/page lifecycleSynchronous one-liners
InitializationBrowserFetcher.DownloadAsync() + LaunchAsyncnew ChromePdfRenderer()
Memory ManagementManual browser recycling requiredAutomatic
Memory Under Load500MB+ with leaks~50MB stable
Cold Start45+ seconds~20 seconds
PDF/A SupportNot availableFull support
PDF/UA AccessibilityNot availableFull support
PDF EditingNot availableMerge, split, stamp, edit
Digital SignaturesNot availableFull support
Thread SafetyLimitedFull
Professional SupportCommunityCommercial with SLA

Platform Support

Library.NET Framework 4.7.2.NET Core 3.1.NET 6-8.NET 10
IronPDFFullFullFullFull
PuppeteerSharpLimitedFullFullPending

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

# Remove PuppeteerSharp
dotnet remove package PuppeteerSharp

# Remove downloaded Chromium binaries (~300MB recovered)
# Delete the .local-chromium folder

# Add IronPDF
dotnet add package IronPdf
# Remove PuppeteerSharp
dotnet remove package PuppeteerSharp

# Remove downloaded Chromium binaries (~300MB recovered)
# Delete the .local-chromium folder

# Add IronPDF
dotnet add package IronPdf
SHELL

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

License Configuration

// Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
// Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";
$vbLabelText   $csharpLabel

Complete API Reference

Namespace Changes

// Before: PuppeteerSharp
using PuppeteerSharp;
using PuppeteerSharp.Media;
using System.Threading.Tasks;

// After: IronPDF
using IronPdf;
using IronPdf.Rendering;
// Before: PuppeteerSharp
using PuppeteerSharp;
using PuppeteerSharp.Media;
using System.Threading.Tasks;

// After: IronPDF
using IronPdf;
using IronPdf.Rendering;
$vbLabelText   $csharpLabel

Core API Mappings

PuppeteerSharp APIIronPDF APINotes
new BrowserFetcher().DownloadAsync()Not neededNo browser download
Puppeteer.LaunchAsync(options)Not neededNo browser management
browser.NewPageAsync()Not neededNo 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 neededAutomatic cleanup
await browser.CloseAsync()Not neededAutomatic cleanup
PdfOptions.FormatRenderingOptions.PaperSizePaper size
PdfOptions.LandscapeRenderingOptions.PaperOrientationOrientation
PdfOptions.MarginOptionsRenderingOptions.MarginTop/Bottom/Left/RightIndividual margins
PdfOptions.PrintBackgroundRenderingOptions.PrintHtmlBackgroundsBackground printing
PdfOptions.HeaderTemplateRenderingOptions.HtmlHeaderHTML headers
PdfOptions.FooterTemplateRenderingOptions.HtmlFooterHTML footers
page.WaitForSelectorAsync()RenderingOptions.WaitFor.HtmlElementIdWait for element

Code Migration Examples

Example 1: Basic HTML to PDF Conversion

Before (PuppeteerSharp):

// NuGet: Install-Package PuppeteerSharp
using PuppeteerSharp;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var browserFetcher = new BrowserFetcher();
        await browserFetcher.DownloadAsync();

        await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
        {
            Headless = true
        });

        await using var page = await browser.NewPageAsync();
        await page.SetContentAsync("<h1>Hello World</h1><p>This is a PDF document.</p>");
        await page.PdfAsync("output.pdf");
    }
}
// NuGet: Install-Package PuppeteerSharp
using PuppeteerSharp;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var browserFetcher = new BrowserFetcher();
        await browserFetcher.DownloadAsync();

        await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
        {
            Headless = true
        });

        await using var page = await browser.NewPageAsync();
        await page.SetContentAsync("<h1>Hello World</h1><p>This is a PDF document.</p>");
        await page.PdfAsync("output.pdf");
    }
}
$vbLabelText   $csharpLabel

After (IronPDF):

// NuGet: Install-Package IronPdf
using IronPdf;

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

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1><p>This is a PDF document.</p>");
        pdf.SaveAs("output.pdf");
    }
}
$vbLabelText   $csharpLabel

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):

// NuGet: Install-Package PuppeteerSharp
using PuppeteerSharp;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var browserFetcher = new BrowserFetcher();
        await browserFetcher.DownloadAsync();

        await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
        {
            Headless = true
        });

        await using var page = await browser.NewPageAsync();
        await page.GoToAsync("https://www.example.com");
        await page.PdfAsync("webpage.pdf");
    }
}
// NuGet: Install-Package PuppeteerSharp
using PuppeteerSharp;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var browserFetcher = new BrowserFetcher();
        await browserFetcher.DownloadAsync();

        await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
        {
            Headless = true
        });

        await using var page = await browser.NewPageAsync();
        await page.GoToAsync("https://www.example.com");
        await page.PdfAsync("webpage.pdf");
    }
}
$vbLabelText   $csharpLabel

After (IronPDF):

// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderUrlAsPdf("https://www.example.com");
        pdf.SaveAs("webpage.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();
        var pdf = renderer.RenderUrlAsPdf("https://www.example.com");
        pdf.SaveAs("webpage.pdf");
    }
}
$vbLabelText   $csharpLabel

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):

// NuGet: Install-Package PuppeteerSharp
using PuppeteerSharp;
using PuppeteerSharp.Media;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var browserFetcher = new BrowserFetcher();
        await browserFetcher.DownloadAsync();

        await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
        {
            Headless = true
        });

        await using var page = await browser.NewPageAsync();
        await page.SetContentAsync("<h1>Custom PDF</h1><p>With landscape orientation and margins.</p>");

        await page.PdfAsync("custom.pdf", new PdfOptions
        {
            Format = PaperFormat.A4,
            Landscape = true,
            MarginOptions = new MarginOptions
            {
                Top = "20mm",
                Bottom = "20mm",
                Left = "20mm",
                Right = "20mm"
            }
        });
    }
}
// NuGet: Install-Package PuppeteerSharp
using PuppeteerSharp;
using PuppeteerSharp.Media;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var browserFetcher = new BrowserFetcher();
        await browserFetcher.DownloadAsync();

        await using var browser = await Puppeteer.LaunchAsync(new LaunchOptions
        {
            Headless = true
        });

        await using var page = await browser.NewPageAsync();
        await page.SetContentAsync("<h1>Custom PDF</h1><p>With landscape orientation and margins.</p>");

        await page.PdfAsync("custom.pdf", new PdfOptions
        {
            Format = PaperFormat.A4,
            Landscape = true,
            MarginOptions = new MarginOptions
            {
                Top = "20mm",
                Bottom = "20mm",
                Left = "20mm",
                Right = "20mm"
            }
        });
    }
}
$vbLabelText   $csharpLabel

After (IronPDF):

// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;
        renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape;
        renderer.RenderingOptions.MarginTop = 20;
        renderer.RenderingOptions.MarginBottom = 20;
        renderer.RenderingOptions.MarginLeft = 20;
        renderer.RenderingOptions.MarginRight = 20;

        var pdf = renderer.RenderHtmlAsPdf("<h1>Custom PDF</h1><p>With landscape orientation and margins.</p>");
        pdf.SaveAs("custom.pdf");
    }
}
// NuGet: Install-Package IronPdf
using IronPdf;
using IronPdf.Rendering;

class Program
{
    static void Main(string[] args)
    {
        var renderer = new ChromePdfRenderer();
        renderer.RenderingOptions.PaperSize = PdfPaperSize.A4;
        renderer.RenderingOptions.PaperOrientation = PdfPaperOrientation.Landscape;
        renderer.RenderingOptions.MarginTop = 20;
        renderer.RenderingOptions.MarginBottom = 20;
        renderer.RenderingOptions.MarginLeft = 20;
        renderer.RenderingOptions.MarginRight = 20;

        var pdf = renderer.RenderHtmlAsPdf("<h1>Custom PDF</h1><p>With landscape orientation and margins.</p>");
        pdf.SaveAs("custom.pdf");
    }
}
$vbLabelText   $csharpLabel

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.A4PaperSize = PdfPaperSize.A4
  • Landscape = truePaperOrientation = PdfPaperOrientation.Landscape
  • MarginOptions.Top = "20mm"MarginTop = 20 (numeric millimeters)

The Memory Leak Problem

PuppeteerSharp is notorious for memory accumulation under sustained load:

// ❌ PuppeteerSharp - Memory grows with each operation
// Requires explicit browser recycling every N operations
for (int i = 0; i < 1000; i++)
{
    var page = await browser.NewPageAsync();
    await page.SetContentAsync($"<h1>Document {i}</h1>");
    await page.PdfAsync($"doc_{i}.pdf");
    await page.CloseAsync(); // Memory still accumulates!
}
// Must periodically: await browser.CloseAsync(); and re-launch

// ✅ IronPDF - Stable memory, reuse renderer
var renderer = new ChromePdfRenderer();
for (int i = 0; i < 1000; i++)
{
    var pdf = renderer.RenderHtmlAsPdf($"<h1>Document {i}</h1>");
    pdf.SaveAs($"doc_{i}.pdf");
    // Memory managed automatically
}
// ❌ PuppeteerSharp - Memory grows with each operation
// Requires explicit browser recycling every N operations
for (int i = 0; i < 1000; i++)
{
    var page = await browser.NewPageAsync();
    await page.SetContentAsync($"<h1>Document {i}</h1>");
    await page.PdfAsync($"doc_{i}.pdf");
    await page.CloseAsync(); // Memory still accumulates!
}
// Must periodically: await browser.CloseAsync(); and re-launch

// ✅ IronPDF - Stable memory, reuse renderer
var renderer = new ChromePdfRenderer();
for (int i = 0; i < 1000; i++)
{
    var pdf = renderer.RenderHtmlAsPdf($"<h1>Document {i}</h1>");
    pdf.SaveAs($"doc_{i}.pdf");
    // Memory managed automatically
}
$vbLabelText   $csharpLabel

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

// Before (PuppeteerSharp - delete entire class)
public class PuppeteerBrowserPool
{
    private readonly ConcurrentBag<IBrowser> _browsers;
    private readonly SemaphoreSlim _semaphore;
    private int _operationCount;
    // ... recycling logic ...
}

// After (IronPDF - simple reuse)
public class PdfService
{
    private readonly ChromePdfRenderer _renderer = new();

    public byte[] Generate(string html)
    {
        return _renderer.RenderHtmlAsPdf(html).BinaryData;
    }
}
// Before (PuppeteerSharp - delete entire class)
public class PuppeteerBrowserPool
{
    private readonly ConcurrentBag<IBrowser> _browsers;
    private readonly SemaphoreSlim _semaphore;
    private int _operationCount;
    // ... recycling logic ...
}

// After (IronPDF - simple reuse)
public class PdfService
{
    private readonly ChromePdfRenderer _renderer = new();

    public byte[] Generate(string html)
    {
        return _renderer.RenderHtmlAsPdf(html).BinaryData;
    }
}
$vbLabelText   $csharpLabel

Critical Migration Notes

Async to Sync Conversion

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

// PuppeteerSharp: Async required
public async Task<byte[]> GeneratePdfAsync(string html)
{
    await new BrowserFetcher().DownloadAsync();
    await using var browser = await Puppeteer.LaunchAsync(...);
    await using var page = await browser.NewPageAsync();
    await page.SetContentAsync(html);
    return await page.PdfDataAsync();
}

// IronPDF: Sync default
public byte[] GeneratePdf(string html)
{
    var renderer = new ChromePdfRenderer();
    return renderer.RenderHtmlAsPdf(html).BinaryData;
}

// Or async when needed
public async Task<byte[]> GeneratePdfAsync(string html)
{
    var renderer = new ChromePdfRenderer();
    var pdf = await renderer.RenderHtmlAsPdfAsync(html);
    return pdf.BinaryData;
}
// PuppeteerSharp: Async required
public async Task<byte[]> GeneratePdfAsync(string html)
{
    await new BrowserFetcher().DownloadAsync();
    await using var browser = await Puppeteer.LaunchAsync(...);
    await using var page = await browser.NewPageAsync();
    await page.SetContentAsync(html);
    return await page.PdfDataAsync();
}

// IronPDF: Sync default
public byte[] GeneratePdf(string html)
{
    var renderer = new ChromePdfRenderer();
    return renderer.RenderHtmlAsPdf(html).BinaryData;
}

// Or async when needed
public async Task<byte[]> GeneratePdfAsync(string html)
{
    var renderer = new ChromePdfRenderer();
    var pdf = await renderer.RenderHtmlAsPdfAsync(html);
    return pdf.BinaryData;
}
$vbLabelText   $csharpLabel

Margin Unit Conversion

PuppeteerSharp uses string units; IronPDF uses numeric millimeters:

// PuppeteerSharp - string units
MarginOptions = new MarginOptions
{
    Top = "1in",      // 25.4mm
    Bottom = "0.75in", // 19mm
    Left = "1cm",     // 10mm
    Right = "20px"    // ~7.5mm at 96dpi
}

// IronPDF - numeric millimeters
renderer.RenderingOptions.MarginTop = 25;    // mm
renderer.RenderingOptions.MarginBottom = 19;
renderer.RenderingOptions.MarginLeft = 10;
renderer.RenderingOptions.MarginRight = 8;
// PuppeteerSharp - string units
MarginOptions = new MarginOptions
{
    Top = "1in",      // 25.4mm
    Bottom = "0.75in", // 19mm
    Left = "1cm",     // 10mm
    Right = "20px"    // ~7.5mm at 96dpi
}

// IronPDF - numeric millimeters
renderer.RenderingOptions.MarginTop = 25;    // mm
renderer.RenderingOptions.MarginBottom = 19;
renderer.RenderingOptions.MarginLeft = 10;
renderer.RenderingOptions.MarginRight = 8;
$vbLabelText   $csharpLabel
PuppeteerSharp ClassIronPDF 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

var pdf1 = renderer.RenderHtmlAsPdf(html1);
var pdf2 = renderer.RenderHtmlAsPdf(html2);
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");
var pdf1 = renderer.RenderHtmlAsPdf(html1);
var pdf2 = renderer.RenderHtmlAsPdf(html2);
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");
$vbLabelText   $csharpLabel

Watermarks

var watermark = new TextStamper
{
    Text = "CONFIDENTIAL",
    FontSize = 48,
    Opacity = 30,
    Rotation = -45
};
pdf.ApplyStamp(watermark);
var watermark = new TextStamper
{
    Text = "CONFIDENTIAL",
    FontSize = 48,
    Opacity = 30,
    Rotation = -45
};
pdf.ApplyStamp(watermark);
$vbLabelText   $csharpLabel

Password Protection

pdf.SecuritySettings.OwnerPassword = "admin";
pdf.SecuritySettings.UserPassword = "readonly";
pdf.SecuritySettings.AllowUserCopyPasteContent = false;
pdf.SecuritySettings.OwnerPassword = "admin";
pdf.SecuritySettings.UserPassword = "readonly";
pdf.SecuritySettings.AllowUserCopyPasteContent = false;
$vbLabelText   $csharpLabel

Digital Signatures

var signature = new PdfSignature("certificate.pfx", "password");
pdf.Sign(signature);
var signature = new PdfSignature("certificate.pfx", "password");
pdf.Sign(signature);
$vbLabelText   $csharpLabel

PDF/A Compliance

pdf.SaveAsPdfA("archive.pdf", PdfAVersions.PdfA3b);
pdf.SaveAsPdfA("archive.pdf", PdfAVersions.PdfA3b);
$vbLabelText   $csharpLabel

Performance Comparison Summary

MetricPuppeteerSharpIronPDFImprovement
First PDF (Cold Start)45s+~20s55%+ faster
Subsequent PDFsVariableConsistentPredictable
Memory Usage500MB+ (grows)~50MB (stable)90% less memory
Disk Space (Chromium)300MB+0Eliminate downloads
Browser DownloadRequiredNot neededZero setup
Thread SafetyLimitedFullReliable concurrency
PDF Generation Time45s20s55% 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

Curtis Chau
Technical Writer

Curtis Chau holds a Bachelor’s degree in Computer Science (Carleton University) and specializes in front-end development with expertise in Node.js, TypeScript, JavaScript, and React. Passionate about crafting intuitive and aesthetically pleasing user interfaces, Curtis enjoys working with modern frameworks and creating well-structured, visually appealing manuals.

...

Read More