Table of Contents

Chromium Setup

CobaltPdf renders PDFs using a real Chromium browser. This page explains how Chromium is delivered to your application and what — if anything — you need to do.

How Chromium Is Distributed

CobaltPdf uses the chromium family of NuGet packages (by devlooped) to bundle Chromium binaries directly inside your NuGet dependency graph. No separate installation step is required.

When you install CobaltPdf, these packages are pulled in as transitive dependencies:

Package Purpose
chromium Core package — provides the Chromium.Path API
chromium.win-x64 Chromium binary for Windows (x64)
chromium.linux-x64 Chromium binary for Linux (x64)

At build time the correct binary for your platform is selected automatically. The Chromium.Path property returns the file-system path to the executable, which CobaltPdf passes directly to Playwright's ExecutablePath launch option.

Note

This is different from the standard playwright install chromium CLI approach. CobaltPdf does not use Playwright's download manager — Chromium arrives as a NuGet package, so nothing needs to be run after dotnet restore.

Why Not playwright install chromium?

The standard Playwright workflow downloads Chromium into a user-profile cache folder via a post-install script or the playwright install CLI command. This has several disadvantages in server and CI environments:

  • Requires network access at deploy time or in the container image build.
  • Writes to a location outside the application's own directory, which can cause permission issues in locked-down environments.
  • Version drift: the installed browser version can differ from the version Playwright was written against.

The NuGet package approach solves all three: the browser is versioned together with the library, ships with the application's binaries, and needs no post-deploy step.

Supported Platforms

Platform Package
Windows x64 chromium.win-x64
Linux x64 chromium.linux-x64

ARM platforms (e.g. Apple Silicon macOS, Linux arm64) are not currently supported by this package set. If you need ARM support, raise an issue on the CobaltPdf repository.

Tip

If Chromium.Path returns null at runtime it means the platform-specific binary package is not present. Verify you are running on a supported platform and that the correct package was restored.

Controlling Which Chromium Binary Is Included

By default, CobaltPdf references both platform packages so that a plain dotnet restore works on any developer machine. Only the binary that matches the target runtime is actually shipped at publish time.

To publish only the binary you need, specify a Runtime Identifier (RID):

# Windows-only output (~200 MB smaller than including both)
dotnet publish -r win-x64 --self-contained false

# Linux-only output
dotnet publish -r linux-x64 --self-contained false

If you want to restrict the restore itself (e.g. in a CI pipeline that only ever targets Linux), you can override the PackageReference conditions in your consuming project's .csproj:

<!-- Include only the Linux binary in your own project -->
<PackageReference Include="chromium.linux-x64" Version="2026.2.1" />

<!-- Suppress the Windows binary that would arrive as a transitive dep -->
<PackageReference Include="chromium.win-x64" Version="2026.2.1" ExcludeAssets="all" />

Linux and Docker

On Linux, Chromium requires several shared libraries that are not included in a minimal base image. Install them in your Dockerfile:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base

# Chromium system dependencies
RUN apt-get update && apt-get install -y \
    libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
    libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
    libxfixes3 libxrandr2 libgbm1 libasound2 \
    --no-install-recommends && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MyApp.dll"]

CobaltPdf automatically adds --no-sandbox, --disable-gpu, and --disable-dev-shm-usage on Linux, so you do not need to configure them manually. Use a CloudEnvironment preset to apply sensible pool sizing for your target environment:

using CobaltPdf;
using CobaltPdf.Configuration;

CobaltEngine.Configure(CloudEnvironment.ConfigureForDocker);
Warning

--no-sandbox (auto-added on Linux) disables the Chromium sandbox. This is standard practice for containerised server rendering, where the container itself provides OS-level isolation. Do not run with --no-sandbox on a machine where users can control the HTML being rendered.

Minimal Debian Package List

The list above covers most environments. If you are using a non-Debian base image or encounter missing library errors, the Playwright Docker documentation provides a comprehensive dependency list.

Verifying the Installation

To confirm Chromium is found correctly, print the path at startup:

Console.WriteLine($"Chromium: {Chromium.Path}");
// e.g. C:\Users\.nuget\packages\chromium.win-x64\2026.2.1\runtimes\win-x64\native\chrome.exe

If the path is null or the file does not exist, check that:

  1. The platform-specific package (chromium.win-x64 or chromium.linux-x64) was restored.
  2. You are not cross-compiling — the binary must match the runtime platform.
  3. The package cache was not corrupted — run dotnet restore --force if in doubt.

Version Updates

Chromium package versions follow the format YYYY.M.D (e.g. 2026.2.1). New releases ship roughly every two weeks alongside Chromium's own release cadence. CobaltPdf pins to a tested Chromium version; updating is a simple NuGet version bump.

Cloud Platform Notes

Platform Notes
Linux VM / bare metal Use CloudEnvironment.ConfigureForLinux. Ensure system libs are installed.
Docker Use CloudEnvironment.ConfigureForDocker. Add Chromium system dependencies to your Dockerfile.
Azure App Service (Linux) Use CloudEnvironment.ConfigureForAzure. System libraries are available; /dev/shm is limited.
Azure Functions Premium Plan Use CloudEnvironment.ConfigureForAzure. Pool persists between invocations on Premium/Dedicated plans.
Azure Functions Consumption Plan ⚠ Not supported. The pool cannot persist across cold-starts. Use the Premium Plan.
AWS ECS / Fargate Use CloudEnvironment.ConfigureForAwsEcs. Use a task with ≥ 1 vCPU and ≥ 2 GB RAM.
AWS Lambda Limited support only. Use CloudEnvironment.ConfigureForLowMemory with a custom container runtime.

See Deployment for step-by-step platform guides.