How the WebKit edition works
CobaltPDF.WebKit renders with WebKitGTK, a Linux rendering engine. That leads to one simple rule:
Production runs on Linux. Development works anywhere. On Windows and macOS the library reaches a Linux environment for you, automatically — you write the exact same C# on your laptop and on your server.
Chromium vs WebKit at a glance
| Runs in production on | On a Windows dev machine | |
|---|---|---|
| CobaltPDF (Chromium) | Windows and Linux | Runs natively — nothing to set up |
| CobaltPDF.WebKit | Linux | Runs automatically via WSL or Docker (see below) |
If you deploy to Windows servers, use Chromium. If you deploy to Linux (where most .NET containers and cloud apps run), either engine works — and WebKit uses a fraction of the memory.
On Linux — production
Nothing to install. On the first render the library downloads a small, self-contained WebKit bundle, then renders in-process — no Docker, no apt, no system packages. This runs as-is on Azure App Service (Linux), AKS, Amazon ECS/Fargate, Lambda, and any Ubuntu or Alpine container.
On Windows — development
You don't have to install Linux yourself. CobaltPDF.WebKit finds a way to reach Linux and uses it automatically, downloading its bundle on first use:
- WSL if it's available (preferred — fast, keeps warm workers ready).
- Docker if WSL isn't there.
If neither exists, the library tells you exactly what to turn on. Pick one of the two options below.
Option A — Enable WSL (recommended)
WSL (Windows Subsystem for Linux) is a built-in Windows feature that runs a real Linux environment next to Windows — no separate PC and no virtual machine to manage. CobaltPDF.WebKit uses it to render.
Turn it on with one command. Open PowerShell as Administrator and run:
wsl --install
Restart when prompted — and that's it. The next time you render, CobaltPDF.WebKit installs its bundle into WSL and renders there.
Already have WSL? You're done. To install a specific distribution:
wsl --install Ubuntu-24.04.
Option B — Use Docker instead
Prefer not to use WSL? Install Docker Desktop and start it. CobaltPDF.WebKit detects Docker and renders through a ready-made image it pulls for you — nothing else to configure.
Docker renders one document at a time, which is fine for development. For the fastest dev loop, WSL is preferred.
On macOS — development
Same as Windows without WSL: install Docker Desktop and the library renders through it automatically (both Intel and Apple Silicon). Deploy to Linux for production.
Recap
- WebKit → Linux in production. Self-provisioning, in-process, very low memory.
- WebKit on Windows / macOS → automatic through WSL or Docker; the bundle is downloaded for you.
- Chromium → Windows or Linux, natively.
- Same fluent API and one license for both engines — see Choosing an Engine.
Want the deeper details — backend selection order, forcing a backend, or stub mode for tests? See Rendering Backends and The portable bundle.