Migrating from PuppeteerSharp to IronPDF moves your PDF generation workflow from a browser automation tool with a 300MB+ Chromium dependency to a purpose-built PDF library with automatic memory management. This guide provides a step-by-step migration path that eliminates the runtime Chromium download, addresses reported memory growth under load, and adds comprehensive PDF manipulation capabilities.
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.
PuppeteerSharp was designed for browser automation, not document generation. This creates fundamental issues when using it for PDFs:
| 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 | Automatic |
| Memory Under Load | Growth reported on heavy workloads | Stable across sustained runs |
| 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 (per upstream guidance) | Full |
| Licensing | MIT (open source) | Commercial license |
| Library | .NET Framework 4.7.2 | .NET Core 3.1 | .NET 6-8 | .NET 10 |
|---|---|---|---|---|
| IronPDF | Full | Full | Full | Full |
| PuppeteerSharp | via netstandard2.0 | Full | Full | Full |
IronPDF's support across modern .NET targets means it slots into most existing applications without compatibility friction.
# Remove PuppeteerSharp
dotnet remove package PuppeteerSharp
# Remove downloaded Chromium binaries (~300MB recovered)
# Delete the .local-chromium folder
# Add IronPDF
dotnet add package IronPdfNo BrowserFetcher.DownloadAsync() required with IronPDF - the rendering engine is bundled automatically.
// Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";' Add at application startup
IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY"// Before: PuppeteerSharp
using PuppeteerSharp;
using PuppeteerSharp.Media;
using System.Threading.Tasks;
// After: IronPDF
using IronPdf;
using IronPdf.Rendering;' Before: PuppeteerSharp
Imports PuppeteerSharp
Imports PuppeteerSharp.Media
Imports System.Threading.Tasks
' After: IronPDF
Imports IronPdf
Imports IronPdf.Rendering| 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 |
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
Imports PuppeteerSharp
Imports System.Threading.Tasks
Module Program
Async Function Main(args As String()) As Task
Dim browserFetcher = New BrowserFetcher()
Await browserFetcher.DownloadAsync()
Await Using browser = Await Puppeteer.LaunchAsync(New LaunchOptions With {
.Headless = True
})
Await Using page = Await browser.NewPageAsync()
Await page.SetContentAsync("<h1>Hello World</h1><p>This is a PDF document.</p>")
Await page.PdfAsync("output.pdf")
End Using
End Using
End Function
End ModuleAfter (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");
}
}Imports IronPdf
Class Program
Shared Sub Main(args As String())
Dim renderer = New ChromePdfRenderer()
Dim pdf = renderer.RenderHtmlAsPdf("<h1>Hello World</h1><p>This is a PDF document.</p>")
pdf.SaveAs("output.pdf")
End Sub
End ClassThis 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.
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
Imports PuppeteerSharp
Imports System.Threading.Tasks
Module Program
Async Function Main(args As String()) As Task
Dim browserFetcher = New BrowserFetcher()
Await browserFetcher.DownloadAsync()
Await Using browser = Await Puppeteer.LaunchAsync(New LaunchOptions With {
.Headless = True
})
Await Using page = Await browser.NewPageAsync()
Await page.GoToAsync("https://www.example.com")
Await page.PdfAsync("webpage.pdf")
End Using
End Using
End Function
End ModuleAfter (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");
}
}Imports IronPdf
Class Program
Shared Sub Main(ByVal args As String())
Dim renderer = New ChromePdfRenderer()
Dim pdf = renderer.RenderUrlAsPdf("https://www.example.com")
pdf.SaveAs("webpage.pdf")
End Sub
End ClassPuppeteerSharp 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.
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
Imports PuppeteerSharp
Imports PuppeteerSharp.Media
Imports System.Threading.Tasks
Module Program
Async Function Main(args As String()) As Task
Dim browserFetcher = New BrowserFetcher()
Await browserFetcher.DownloadAsync()
Await Using browser = Await Puppeteer.LaunchAsync(New LaunchOptions With {
.Headless = True
})
Await Using 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 With {
.Format = PaperFormat.A4,
.Landscape = True,
.MarginOptions = New MarginOptions With {
.Top = "20mm",
.Bottom = "20mm",
.Left = "20mm",
.Right = "20mm"
}
})
End Using
End Using
End Function
End ModuleAfter (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
Imports IronPdf
Imports IronPdf.Rendering
Class Program
Shared Sub Main(ByVal args As String())
Dim 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
Dim pdf = renderer.RenderHtmlAsPdf("<h1>Custom PDF</h1><p>With landscape orientation and margins.</p>")
pdf.SaveAs("custom.pdf")
End Sub
End ClassThis 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.A4Landscape = true → PaperOrientation = PdfPaperOrientation.LandscapeMarginOptions.Top = "20mm" → MarginTop = 20 (numeric millimeters)Users have reported memory accumulation with PuppeteerSharp under sustained load, typically mitigated by manual browser recycling:
// PuppeteerSharp - memory growth typically requires periodic recycling
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();
}
// Recommended: await browser.CloseAsync(); and re-launch every N operations
// IronPDF - reuse a single renderer across operations
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
}Imports PuppeteerSharp
Imports IronPdf
' PuppeteerSharp - memory growth typically requires periodic recycling
For i As Integer = 0 To 999
Dim page = Await browser.NewPageAsync()
Await page.SetContentAsync($"<h1>Document {i}</h1>")
Await page.PdfAsync($"doc_{i}.pdf")
Await page.CloseAsync()
Next
' Recommended: Await browser.CloseAsync() and re-launch every N operations
' IronPDF - reuse a single renderer across operations
Dim renderer As New ChromePdfRenderer()
For i As Integer = 0 To 999
Dim pdf = renderer.RenderHtmlAsPdf($"<h1>Document {i}</h1>")
pdf.SaveAs($"doc_{i}.pdf")
' Memory managed automatically
NextIronPDF 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 _browsers As ConcurrentBag(Of IBrowser)
Private ReadOnly _semaphore As SemaphoreSlim
Private _operationCount As Integer
' ... recycling logic ...
End Class
' After (IronPDF - simple reuse)
Public Class PdfService
Private ReadOnly _renderer As New ChromePdfRenderer()
Public Function Generate(html As String) As Byte()
Return _renderer.RenderHtmlAsPdf(html).BinaryData
End Function
End ClassPuppeteerSharp 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;
}Imports System.Threading.Tasks
Imports PuppeteerSharp
' PuppeteerSharp: Async required
Public Async Function GeneratePdfAsync(html As String) As Task(Of Byte())
Await (New BrowserFetcher()).DownloadAsync()
Await Using browser = Await Puppeteer.LaunchAsync(...)
Await Using page = Await browser.NewPageAsync()
Await page.SetContentAsync(html)
Return Await page.PdfDataAsync()
End Using
End Using
End Function
' IronPDF: Sync default
Public Function GeneratePdf(html As String) As Byte()
Dim renderer = New ChromePdfRenderer()
Return renderer.RenderHtmlAsPdf(html).BinaryData
End Function
' Or async when needed
Public Async Function GeneratePdfAsync(html As String) As Task(Of Byte())
Dim renderer = New ChromePdfRenderer()
Dim pdf = Await renderer.RenderHtmlAsPdfAsync(html)
Return pdf.BinaryData
End FunctionPuppeteerSharp 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 With {
.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 Class | IronPDF Placeholder |
|---|---|
<span class='pageNumber'> | {page} |
<span class='totalPages'> | {total-pages} |
<span class='date'> | {date} |
<span class='title'> | {html-title} |
After migrating to IronPDF, you gain capabilities that PuppeteerSharp cannot provide:
var pdf1 = renderer.RenderHtmlAsPdf(html1);
var pdf2 = renderer.RenderHtmlAsPdf(html2);
var merged = PdfDocument.Merge(pdf1, pdf2);
merged.SaveAs("merged.pdf");Dim pdf1 = renderer.RenderHtmlAsPdf(html1)
Dim pdf2 = renderer.RenderHtmlAsPdf(html2)
Dim merged = PdfDocument.Merge(pdf1, pdf2)
merged.SaveAs("merged.pdf")var watermark = new TextStamper
{
Text = "CONFIDENTIAL",
FontSize = 48,
Opacity = 30,
Rotation = -45
};
pdf.ApplyStamp(watermark);Dim watermark As New TextStamper With {
.Text = "CONFIDENTIAL",
.FontSize = 48,
.Opacity = 30,
.Rotation = -45
}
pdf.ApplyStamp(watermark)pdf.SecuritySettings.OwnerPassword = "admin";
pdf.SecuritySettings.UserPassword = "readonly";
pdf.SecuritySettings.AllowUserCopyPasteContent = false;pdf.SecuritySettings.OwnerPassword = "admin"
pdf.SecuritySettings.UserPassword = "readonly"
pdf.SecuritySettings.AllowUserCopyPasteContent = Falsevar signature = new PdfSignature("certificate.pfx", "password");
pdf.Sign(signature);Dim signature = New PdfSignature("certificate.pfx", "password")
pdf.Sign(signature)pdf.SaveAsPdfA("archive.pdf", PdfAVersions.PdfA3b);pdf.SaveAsPdfA("archive.pdf", PdfAVersions.PdfA3b)| 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 |
PuppeteerSharp NuGet package.local-chromium folder to reclaim ~300MB disk spaceIronPdf NuGet package: dotnet add package IronPdfBrowserFetcher.DownloadAsync() callsPuppeteer.LaunchAsync() and browser managementpage.SetContentAsync() + page.PdfAsync() with RenderHtmlAsPdf()page.GoToAsync() + page.PdfAsync() with RenderUrlAsPdf()
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.
IronPDF is a part of IRONSUITE
10 .NET API products for your office documents
When you need your PDF to look like HTML, fast.
