Table of Contents

Choosing an Engine

CobaltPDF ships as two separate NuGet packages that share the same fluent API and the same license key:

CobaltPDF (Chromium) CobaltPDF.WebKit (WebKit)
Engine Real Chromium (Playwright) Headless WebKitGTK
Best for Maximum fidelity; Windows and Linux Linux-native, low-memory, high-volume
Idle memory ~240 MB idle heap ~130 MB idle heap (≈40% less; released between renders)
Setup Pulls the chromium.* runtime package Self-provisions a portable bundle on first run (managed Linux: no apt; a plain Docker image needs the webkit2gtk runtime)
Namespace CobaltPdf CobaltPdf.WebKit

The API is identical

Both expose the same CobaltEngine type and the same fluent methods, so code written against one runs unchanged against the other — only the using (namespace) differs:

// Chromium
using CobaltPdf;
var pdf = await new CobaltEngine().RenderUrlAsPdfAsync("https://example.com");

// WebKit — same code, different namespace
using CobaltPdf.WebKit;
var pdf = await new CobaltEngine().RenderUrlAsPdfAsync("https://example.com");

Everything in these guides — rendering, cookies, headers/footers, watermarks, encryption, lazy loading, wait strategies, metadata, splitting/merging, dependency injection — applies to both engines. Where an engine differs, you'll see a note like this:

Note

WebKit: self-provisions its bundle on Linux. Chromium: ships the browser via the chromium.* packages.

One CobaltPDF.Requests model works against either engine, so a microservice can swap engines without changing its callers.

Which should I pick?

  • Pixel-perfect fidelity, or you deploy on Windows → CobaltPDF (Chromium).
  • Linux containers / serverless, memory- or cost-constrained, high throughput → CobaltPDF.WebKit.
  • Not sure → start with Chromium for fidelity; switch to WebKit later by changing the package + using if memory/cost matters. Output won't be pixel-identical across engines (different layout/font engines), but the API and your code stay the same.

Engine-specific guides