CobaltPDF 1.6.2

Prefix Reserved

dotnet add package CobaltPDF --version 1.6.2

NuGet\Install-Package CobaltPDF -Version 1.6.2

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="CobaltPDF" Version="1.6.2" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="CobaltPDF" Version="1.6.2" />
                    

                            Directory.Packages.props

<PackageReference Include="CobaltPDF" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add CobaltPDF --version 1.6.2

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: CobaltPDF, 1.6.2"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package CobaltPDF@1.6.2

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=CobaltPDF&version=1.6.2
                    

                            Install as a Cake Addin

#tool nuget:?package=CobaltPDF&version=1.6.2
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

CobaltPDF

Pixel-perfect PDFs from HTML and URLs in 3 lines of C#. Powered by a managed Chromium browser pool that stays warm between renders — every request reuses a ready browser instead of paying the Chromium startup cost.

cobaltpdf.com · Documentation · Quick start · Pricing

Free for any purpose, with no time limit. Every feature works out of the box—no trial countdowns, no feature gating, and no restrictions. Use it freely for prototyping, learning, development, or testing; the only difference is that generated PDFs carry a watermark until you activate a license key.

dotnet add package CobaltPDF

using CobaltPdf;

// Render a URL to PDF
await new CobaltEngine()
    .RenderUrlAsPdfAsync("https://example.com")
    .SaveAsAsync("website.pdf");

// Render an HTML string to PDF
await new CobaltEngine()
    .RenderHtmlAsPdfAsync("<h1>Hello, World!</h1>")
    .SaveAsAsync("hello.pdf");

// Render a local HTML file to PDF
await new CobaltEngine()
    .RenderHtmlFileAsPdfAsync("invoice.html")
    .SaveAsAsync("invoice.pdf");

That's it. Chromium is bundled automatically — nothing else to install.

What's new in 1.6.0

Image compression on by default — embedded images are re-encoded to shrink output PDFs (often several times smaller on image-heavy pages). Opt out with WithCompression(false) for raw, lossless output. (WithoutPostProcessing() is now a deprecated alias for WithCompression(false).)
Desktop-layout rendering by default — captures the full ~1280px desktop layout scaled to fit the page (matching the WebKit edition), instead of reflowing to the narrow print width. Call WithMediaType(CssMediaType.Print) for the classic Chrome-print reflow.
WithViewportSize(width[, height]) — set the render viewport; a tall height triggers IntersectionObserver lazy images without scrolling.
WithEagerImages() — force lazy-loaded images (loading="lazy" and data-src/data-srcset) to load before rendering.
Default User-Agent now a desktop Chrome UA (overridable via WithUserAgent(...)), so UA-sensitive sites serve the same markup as the WebKit edition.
Pool backpressure & metrics — PoolOptions.MaxQueueDepth + PoolBusyException (return HTTP 503 instead of timing out when saturated); CobaltEngine.GetPoolStatistics() for health/metrics. MaxSize now auto-sizes to the host (vCPU and memory aware).

All additive or behaviour-toggled; see the changelog for details.

Go further

var pdf = await new CobaltEngine()
    .WithPrintBackground()
    .WithPaperFormat("A4")
    .WithMargins(new MarginOptions(20, 15, 20, 15))
    .WithHeader("<div style='font-size:10px;text-align:center;width:100%'>My Report</div>")
    .WithFooter("<div style='font-size:10px;text-align:center;width:100%'>Page <span class='pageNumber'></span> of <span class='totalPages'></span></div>")
    .WithWatermark(WatermarkOptions.WithText("DRAFT", WatermarkStyle.SoftGray))
    .WithEncryption(new PdfEncryptionOptions
    {
        UserPassword  = "viewer-pass",
        OwnerPassword = "admin-secret",
        AllowPrinting = true,
        AllowCopying  = false,
    })
    .WithMetadata(m =>
    {
        m.Title  = "Q4 Financial Report";
        m.Author = "Finance Team";
    })
    .AddCookie("session", "abc123")
    .WithWaitStrategy(WaitOptions.DefaultNetworkIdle)
    .RenderUrlAsPdfAsync("https://example.com/report");

pdf.SaveAs("report.pdf");

Every option chains. Every method has a sensible default. Use only what you need.

Split, extract & merge

Pull pages out of any PDF — freshly rendered or loaded from disk — or merge documents back together. Pure in-process post-processing; no browser involved.

var pdf = await new CobaltEngine().RenderHtmlAsPdfAsync(html);

// One file per page
foreach (var (page, i) in pdf.SplitIntoPages().Select((p, i) => (p, i)))
    page.SaveAs($"page_{i + 1}.pdf");

// Extract a range, or load an existing PDF and take what you need
pdf.ExtractPages(0, 2).SaveAs("first-three.pdf");
PdfDocument.FromFile("legacy.pdf").ExtractPage(0).SaveAs("cover.pdf");

// Merge documents
PdfDocument.Merge(coverPdf, bodyPdf, appendixPdf).SaveAs("combined.pdf");

Features


Fluent API	Chain any combination of options in a single expression
Headers, footers & watermarks	HTML templates with `pageNumber`/`totalPages` tokens, built-in watermark presets, and opt-in `.WithRasterize()` to bake the watermark into the page pixels
AES-256 encryption	User + owner passwords with print/copy/modify permissions
Split, extract & merge	`PageCount`, `ExtractPage(s)`, `SplitIntoPages`, `FromFile`, `FromBytes`, `Merge` — works on any PDF
Wait strategies	Network idle, CSS selector, JS expression, fixed delay, or `cobaltNotifyRender()` signal
Cookies & storage	Inject cookies, `localStorage`, and `sessionStorage` before navigation
Custom JavaScript	Execute JS before capture to manipulate the DOM or set application state
Custom fonts	Load `.ttf`, `.otf`, `.woff`, `.woff2` from a local directory
Lazy loading	Scroll N viewport-heights to trigger IntersectionObserver content
Metadata	Embed title, author, subject, and keywords in the PDF
DI support	`services.AddCobaltPdf()` with singleton lifecycle for ASP.NET Core
Cloud-ready	Built-in presets for Docker, Azure, AWS ECS/Fargate, and Lambda
Microservice mode	Lightweight `CobaltPDF.Requests` package for JSON-based rendering without Chromium

ASP.NET Core

// Program.cs
CobaltEngine.SetLicense(builder.Configuration["CobaltPdf:LicenseKey"]!);
builder.Services.AddCobaltPdf(CloudEnvironment.ConfigureForDocker);

// Controller — inject CobaltEngine as a singleton
public class ReportController(CobaltEngine renderer) : ControllerBase
{
    [HttpGet("export")]
    public async Task<IActionResult> Export(CancellationToken ct)
    {
        var pdf = await renderer
            .WithPrintBackground()
            .RenderUrlAsPdfAsync("https://app.example.com/report", ct);

        return File(pdf.BinaryData, "application/pdf", "report.pdf");
    }
}

Cloud presets: ConfigureForDocker | ConfigureForAzure | ConfigureForAwsEcs | ConfigureForLowMemory | ConfigureForLinux

Requirements


.NET	8.0 or later
OS	Windows x64, Linux x64

Targets net8.0 — fully compatible with .NET 8, 9, and 10.

Need a lighter engine?

CobaltPDF.WebKit is our standalone WebKit-based sister library: the same CobaltEngine type and fluent API, with up to 96% lower idle memory and 57% faster warm renders — built for high-volume rendering on Linux containers. Your CobaltPDF license key activates both libraries. Compare the engines →

License

Free to evaluate indefinitely — no time limit, no feature restrictions. Every render path, configuration option, and cloud preset works without a license key. The only difference: unlicensed PDFs include a watermark.

When you're ready to ship to production, activate a license key to remove the watermark:

CobaltEngine.SetLicense("YOUR-LICENSE-KEY");

View pricing

Product	Compatible and additional computed target framework versions.
.NET	net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net8.0
- chromium (>= 2026.5.16)
- chromium.linux-x64 (>= 2026.5.16)
- chromium.win-x64 (>= 2026.5.16)
- CobaltPDF.Requests (>= 1.6.1)
- Magick.NET-Q8-AnyCPU (>= 14.14.0)
- Microsoft.Extensions.DependencyInjection (>= 10.0.8)
- Microsoft.Playwright (>= 1.60.0)
- PDFsharp (>= 6.2.4)
- System.Formats.Asn1 (>= 10.0.8)

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.6.2	0	6/21/2026
1.5.0	109	6/13/2026
1.4.0	144	5/25/2026
1.3.0	186	3/1/2026
1.2.2	167	2/27/2026

v1.6.2
     - IMPORTANT FIX: CloudEnvironment.ConfigureForAzure and ConfigureForLowMemory no longer add --single-process. That flag crashes the Chromium renderer on multi-page / non-trivial PDFs (only trivial single-page renders survived it), so 1.6.1 could fail real renders on Azure when these presets were used. Upgrading from 1.6.1 is strongly recommended. The presets now use the stable multi-process model; --single-process remains available as a manual flag for advanced single-short-page use only.
     - The bundled Linux dependencies (introduced in 1.6.1) now activate ONLY when the host is actually missing Chromium's graphics stack, so Linux hosts that already provide the libraries render byte-for-byte as before.

     v1.6.1
     - Linux self-contained dependencies: the package ships Chromium's OS-level shared libraries (glibc-compatible, including the NSS PKCS#11 modules and base fonts) under runtimes/linux-x64/native/cobalt-linux-deps and points the browser's loader at them automatically on Linux (LD_LIBRARY_PATH + fontconfig, set on the chrome process only). This lets the Chromium edition run on a STOCK Azure Functions Linux plan or a slim container with a plain code deploy: no custom container, no apt packages. No effect on Windows.

     v1.6.0
     - Auto-sized concurrency: PoolOptions.MaxSize now defaults to a host-aware value (the smaller of the vCPU count and how many browsers fit in ~75% of detected memory at ~400 MB each, clamped 1-8) instead of a fixed 5 — so it stays safe on memory-constrained hosts (e.g. an 8-vCPU/2 GB container caps at ~3 rather than OOMing). Falls back to the clamped vCPU count if memory can't be detected. Always overridable.
     - Pool backpressure and metrics (parity with the WebKit edition): new PoolOptions.MaxQueueDepth + PoolBusyException let a saturated pool fast-fail extra requests so the host can return HTTP 503 instead of a slow timeout (default 0 = unbounded = unchanged behaviour). New CobaltEngine.GetPoolStatistics() / CobaltPoolStatistics expose live pool gauges and lifetime counters for health/metrics endpoints (TotalRenderRetries is always 0 here; the Chromium pool has no render-retry).
     - Image compression: rendered PDFs now have their embedded images re-encoded to shrink the file — typically several times smaller on image-heavy pages — bringing the Chromium edition in line with the CobaltPDF.WebKit edition's optimisation. ON by default; call WithCompression(false) (or PdfRequest.Compress = false) to keep Chromium's raw, larger, lossless output. Powered by Magick.NET (Apache-2.0). WithoutPostProcessing() is now deprecated (use WithCompression(bool)) and is no longer a no-op on Chromium.
     - Default User-Agent now matches the CobaltPDF.WebKit edition (a desktop Chrome/124 UA via PdfOptions.DefaultUserAgent) so both engines are served the same markup by UA-sensitive sites. Override per render with WithUserAgent(...) / PdfRequest.UserAgent, or set it null/empty to use the bundled Chromium's own UA.
     - DEFAULT OUTPUT CHANGE: renders now capture the full desktop layout (screen media, ~1280px wide) scaled to fit the page, matching the CobaltPDF.WebKit edition, instead of reflowing to the narrow print width. The paper stays its true size (e.g. A4). This also wires up the previously-ignored MediaType option — set WithMediaType(CssMediaType.Print) to restore the old Chrome-print reflow.
     - Added WithViewportSize(width[, height]) for parity with the WebKit edition (sets the render viewport; a tall height triggers IntersectionObserver lazy images without scrolling).
     - Added WithEagerImages() / PdfOptions.ForceEagerImages: forces lazy-loaded images to load before rendering. Chromium already force-loads native loading="lazy" images at print time; this additionally promotes the JavaScript lazy-load convention (data-src / data-srcset → live src / srcset) that the print path cannot. Opt-in; default rendering output is unchanged. API-identical to the CobaltPDF.WebKit edition.

     v1.5.0
     - Added PDF page splitting, extraction, and merging on PdfDocument: PageCount, ExtractPage, ExtractPages (range or subset), SplitIntoPages, FromFile, FromBytes, and Merge. Works on any PDF, on any OS — no browser involved.
     - Added watermark rasterization: WatermarkOptions.Rasterize / .WithRasterize() flattens a watermark into an image baked into every page, so it has no selectable text and no separately deletable object in a PDF editor. Opt-in; default behaviour unchanged.
     - Encryption upgraded from AES-128 to AES-256 (security handler V5/R6). The WithEncryption API and all password/permission behaviour are unchanged — only the cipher strength improved.
     - Added WithoutPostProcessing() as an accepted no-op for drop-in compatibility with CobaltPDF.WebKit (Chromium's PDF backend already subsets fonts and compresses images natively, so it has no effect here).
     - CobaltPDF.Requests dependency updated to v1.5.0, forwarding the watermark Rasterize flag and the new SkipPostProcessing flag through PdfRequest.ExecuteAsync (SkipPostProcessing is honoured by the WebKit edition and ignored here).
     - All changes are backward compatible; no public API was renamed or removed.

     v1.4.1
     - WithUserAgent, WithHttpHeader, and WithHttpHeaders are now declared on the IPdfGenerator and IPdfGeneratorFinal interfaces (previously only on CobaltEngine).
     - Fixed AddCookie(name, value) without an explicit domain throwing "Invalid cookie fields" when the final URL is localhost, an IP address, or a single-label intranet hostname. Such cookies are now registered as standard host-only cookies.

     v1.4.0
     - Updated bundled Chromium from 2026.2.1 to 2026.5.16 to resolve upstream security advisories.
     - Dropped .NET 6.0 target. The package now targets .NET 8.0 (compatible with .NET 8, 9, and 10). Consumers on .NET 6 should stay on v1.3.0 or upgrade their runtime; .NET 6 is out of Microsoft support as of November 2024.

     v1.3.0
     - Added multi-targeting: the package now supports both .NET 6.0 and .NET 8.0+, broadening compatibility with projects on .NET 6, 7, 8, 9, and 10.

     v1.2.2
     - Fixed Chromium default header/footer appearing when only one template is provided. Setting a footer no longer adds an unwanted date header, and vice versa.
     - WithCustomJS now waits for the page to be fully loaded before executing, so dynamically-injected elements (e.g. cookie consent buttons) are available.
     - Client-side redirects (e.g. bbc.com → bbc.co.uk) are now detected before cookies, custom JS, and wait strategies run.
     - Fixed WithLazyLoadPages not working when combined with WithCustomJS or WithWaitStrategy.

     v1.2.0
     - Added transitive MSBuild props to auto-configure RuntimeIdentifiers (win-x64, linux-x64) for consuming projects, fixing Chromium.Path resolution in Docker and cloud deployments.
     - No manual .csproj changes needed for Docker/Azure/AWS deployments.

     v1.1.0
     - Consolidated all public types into the CobaltPdf namespace (single using statement).
     - Added WithPrintBackground(), WithScale(), WithPageRanges(), WithPageSize() to the fluent API.
     - Extracted WatermarkOptions, PdfEncryptionOptions, MetadataOptions to top-level classes.

     v1.0.1
     - Added WithPaperFormat() and WithMargins() to the fluent API.
     - Added CancellationToken support to all render methods.
     - Added SaveAsAsync() and Task<PdfDocument> fluent chaining extensions.
     - Added CloudEnvironment presets for Linux, Docker, Azure, and AWS.
     - Improved browser pool with linked CancellationTokenSource for lease timeouts.