DEV Community: Florentin Badea

SelectPdf vs IronPDF. An IronPDF alternative for .NET.

Florentin Badea — Thu, 22 Oct 2026 14:03:45 +0000

Florentin Badea

Oct 22

SelectPdf vs IronPDF in 2026, measured on Windows and Linux

#dotnet #csharp #pdf #benchmark

7 min read

SelectPdf vs IronPDF in 2026, measured on Windows and Linux

Florentin Badea — Thu, 22 Oct 2026 11:26:04 +0000

Most comparisons still describe the Windows-only SelectPdf of 2025. Here is what changed, and what an open benchmark measured on the same machine under both systems.

I'm the founder of SelectPdf. The numbers below come from an open benchmark that anyone can re-run, and this article also says where IronPDF comes out ahead.

Search for "SelectPdf vs IronPDF" today and most results will tell you that SelectPdf runs only on Windows, renders with WebKit and cannot redact PDFs or convert Word files. Until October 2026 that was a fair description of the classic SelectPdf library. It does not describe the current one, so this article compares the two libraries as they stand in October 2026, with measurements instead of adjectives.

What changed in SelectPdf in 2026

SelectPdf 26.4, released in October 2026, introduced SelectPdf.Universal, a new library on NuGet:

It runs on Windows (x64 and x86), Linux (x64 and ARM64), macOS and in Docker.
It targets .NET 8, .NET 10 and .NET Standard 2.0.
It renders HTML with Chromium only: Chromium 154 in version 26.5.
Besides HTML to PDF, it creates, merges, splits and edits PDF documents, fills forms, extracts text, redacts text, images and form fields, and signs with certificates, USB tokens, smart cards and HSMs, with long-term validation. It also converts Word documents to PDF and produces PDF/A and PDF/UA output.

Version 26.5 added a remote engine, so the library also runs on Alpine Linux and in Kubernetes.

The classic SelectPdf library is still maintained for Windows projects, with its WebKit, Blink and Chromium engines. One license covers both libraries.

The same task in both libraries

Converting an HTML string looks much the same in both:

// SelectPdf.Universal
using SelectPdf.Universal;

HtmlToPdf converter = new HtmlToPdf();
PdfDocument doc = converter.ConvertHtmlString(html);
doc.Save("output.pdf");
doc.Close();

// IronPDF
using IronPdf;

var renderer = new ChromePdfRenderer();
var pdf = renderer.RenderHtmlAsPdf(html);
pdf.SaveAs("output.pdf");

The differences show up in the details. SelectPdf sets margins in points where IronPDF uses millimetres, and its page-number placeholders are {page_number} and {total_pages} rather than {page} and {total-pages}. Moving a project across is mostly renaming and converting units; a migration guide on GitHub shows each change on a working project.

Both libraries render HTML with Chromium, but not the same version. SelectPdf.Universal 26.5 ships Chromium 154, which has been stable since September 2026. IronPDF 2026.10.3 ships Chromium 109, stable since January 2023, according to the libcef binary in its native packages. CSS and JavaScript features added to Chromium since then will not appear in IronPDF's output.

How it was measured

The numbers come from an open benchmark of ten .NET PDF libraries, run on 2026-10-15. It used SelectPdf.Universal 26.5.0 and IronPdf 2026.10.3, the latest versions on NuGet that day.

One machine (Intel Core Ultra 9 275HX, 24 logical cores) ran Windows, and Ubuntu 24.04 under WSL2 on the same hardware.
Speed is the median of 9 conversions per page in a warm process, over 18 test pages, with the libraries interleaved so that machine drift is spread out.
Throughput is the number of conversions a minute, measured for 60 seconds with 8 conversions running at once.
Memory is measured across the library's whole process tree, so a browser engine's helper processes count too.
Fidelity compares each PDF, tile by tile, with a Chrome screenshot of the same page (SSIM, where 1.0 means identical).
Every PDF/A and PDF/UA file is validated by veraPDF.

The harness, the test pages and the raw results are all public, and the links are at the end.

On Windows, IronPDF is faster

Windows	SelectPdf	IronPDF
HTML to PDF, average over 18 pages	212 ms	186 ms
Pages converted faster	4 of 18	14 of 18
Cold start (new process, one page)	714 ms	657 ms
Conversions a minute, 8 at once	1,078	1,735
Memory, 8 conversions at once	467 MB	788 MB
Memory over 1,000 conversions (MB)	140 → 156	226 → 630

On Windows, IronPDF converted most pages faster, started faster and completed more conversions a minute. SelectPdf was faster on four pages: long documents, HTML strings, web fonts and CJK text. It also used less memory, and its memory barely grew over 1,000 conversions in one process.

On Linux, SelectPdf is faster

Linux (Ubuntu 24.04, WSL2)	SelectPdf	IronPDF
HTML to PDF, average over 18 pages	134 ms	169 ms
Pages converted faster	14 of 18	4 of 18
Cold start (new process, one page)	745 ms	1,090 ms
Conversions a minute, 8 at once	2,597	1,520
Memory, 8 conversions at once	727 MB	1,322 MB
Memory over 1,000 conversions (MB)	369 → 389	451 → 1,076

On Linux the order reverses. SelectPdf converted 14 of the 18 pages faster, started faster and completed more conversions a minute at every concurrency the benchmark tested (1, 4 and 8, with both the synchronous and the asynchronous API). IronPDF was faster on a page with a JavaScript chart, on lazy-loaded and large images, and on the SelectPdf home page.

The averages are geometric means of the per-page medians.

Output quality

Output	SelectPdf	IronPDF
Content checks passed	46 of 48	41 of 48
Fidelity vs Chrome (Windows)	0.984	0.928
Fidelity vs Chrome (Linux)	0.984	0.919
PDF/A, PDF/UA, PDF/X files compliant	17 of 17	5 of 17
Accessibility tag checks	112 of 112	42 of 112
Word to PDF, 8-page report: pages	8 of 8	6 of 8
Word to PDF, 8-page report: fidelity	0.98	0.47

The content checks look for things such as missing text, cut-off content, embedded fonts, loaded images, page numbers, bookmarks, form fields and encryption. SelectPdf missed one wide-content page. IronPDF missed bookmarks, the requested encryption algorithm, lazy-loaded images, the wide-content page and an isolation check.

IronPDF offers fewer standard levels (it has no PDF/A-2u or PDF/A-3u option, for example), and several of the files it did produce failed veraPDF validation.

Both libraries merge, split, watermark, fill forms, sign, redact and produce Factur-X invoices, and every one of those checks passed for both. IronPDF was faster at redaction, signing and Factur-X; SelectPdf was faster at extracting text from long documents and at converting the 8-page Word report.

Docker

On the official mcr.microsoft.com/dotnet/runtime:8.0 image, with nothing installed:

SelectPdf converted pages both as root and as a non-root user. Its native package bundles the Chromium libraries it needs, so the Dockerfile has no apt-get step. Linux needs glibc 2.30 or later.
IronPDF converted pages as root, but failed as a non-root user. Following IronPDF's own Docker guide, which installs 24 OS packages, it worked as both.

IronPDF has the smaller footprint: its published app is 315 MB on linux-x64, against 450 MB for SelectPdf.

Price

Both libraries sell perpetual licenses with one year of updates and support included, and both charge a yearly renewal for updates after that. The prices below are in USD, read from both vendors' pages on 2026-10-22.

SelectPdf licenses count developers and deployment machines. One license covers both SelectPdf.Universal and the classic library.

SelectPdf	Developers	Deployment	Price	Renewal/year
Single Developer	1	1 machine	$499	$299
Single Developer OEM	1	unlimited, OEM	$799	$499
5-Developers	5	up to 10 machines	$799	$499
5-Developers OEM	5	unlimited, OEM	$1,099	$699
Enterprise	unlimited	up to 100 machines	$1,199	$799
Enterprise OEM	unlimited	unlimited, OEM	$1,599	$999

The renewal prices apply when you renew before the maintenance plan expires; after it has lapsed, renewal costs $399 to $1,299. Licenses can also be bought with a 3-year or 5-year maintenance plan.

IronPDF licenses count developers, locations and projects. Using it in SaaS or in software you redistribute needs the OEM Redistribution add-on, which the licensing page offers with Plus, Professional and Unlimited, but not with Lite.

IronPDF	Developers	Locations/projects	Price	Renewal/year
Lite	1	1 / 1	$999	$599
Plus	3	3 / 3	$1,499	$899
Professional	10	10 / 10	$2,399*	$1,799
Unlimited	unlimited	unlimited	$4,799*	$3,599
OEM Redistribution add-on (Plus and up)			+$1,999

* Shown as a 20% discount from $2,999 and $5,999 on 2026-10-22; Iron Software announces those prices from November 1, 2026

The two price lists are not cut the same way, so here are the closest matches:

	SelectPdf	IronPDF
1 developer	$499	$999 (Lite)
1 developer, SaaS or redistributed	$799 (OEM)	$3,498 (Plus + OEM add-on)
5 developers	$799	$2,399 (Professional)
Unlimited developers	$1,199	$4,799 (Unlimited)
Unlimited developers, OEM	$1,599	$6,798 (Unlimited + OEM)
Renewal for 1 developer, a year	$299	$599

The matches are approximate: IronPDF's smallest license with the OEM add-on is Plus, for three developers; its smallest for five developers is Professional, for ten; and SelectPdf's Enterprise license covers up to 100 deployment machines, where IronPDF's Unlimited has no location limit.

SelectPdf also has a free Community Edition that converts HTML to PDF with no watermark, including in production, for documents of up to 5 pages.

Which one to choose

Choose IronPDF if your servers run Windows and raw conversion speed matters most to you, or if you need a smaller deployment.

Choose SelectPdf if you deploy to Linux or Docker, if you need a recent Chromium, or if you need PDF/A, PDF/UA or accessible output that passes validation. The same applies if you would rather not install OS packages in your images, or if license cost matters: SelectPdf costs less in each of the matches above.

In either case, convert a few of your own documents with both libraries before you decide. The benchmark pages are not your pages.

Limitations

There was one machine and one run per operating system. Linux ran in WSL2 on the same hardware, not on a separate server, so treat the numbers as relative.
The commercial libraries ran on their trials, with evaluation watermarks masked before the images were compared.
Each library was configured the way its vendor documents. If the setup is wrong for either library, the adapter code is public and corrections are welcome.
The benchmark is maintained by SelectPdf. Public code and raw data make it checkable; they do not make it independent.

We compared 10 .NET PDF libraries on the same 14 C# tasks: here is the open benchmark

Florentin Badea — Mon, 19 Oct 2026 12:41:10 +0000

Choosing a PDF library for .NET usually means reading vendor pages, running a hello world and hoping the result holds up on real documents. We wanted something more useful: ten C# PDF libraries put through the same 14 tasks, each with a compilable sample, and measured on the same machine under Windows and Linux for speed, throughput, memory, output correctness, fidelity to Chrome, PDF/A and PDF/UA output, and Docker deployment.

Everything is public: the harness, the 18 test pages, the raw results and every sample, so you can check any number or re-run it on your own hardware. This post explains how the measurements work, where each library comes out ahead (it is not the same library every time), and what the results can and cannot tell you.

Disclosure: we make SelectPdf, one of the ten libraries in this comparison.

Why PDF library comparisons mislead

Most comparisons you find measure one library on one page with its defaults, and the defaults differ more than you would expect. Some libraries print with print CSS media and drop backgrounds; some lay the page out at 1,024 pixels and scale it; some use Letter paper, others A4. One converts HTML with Chromium, another with its own layout engine that does not run JavaScript. A "hello world" timing tells you little about an invoice with web fonts, a chart drawn by script or a 40-page report.

So we built the comparison around the same work for everyone.

Fourteen tasks, one sample each

Every library gets one compilable console project per task: hello world, an HTML string, a URL, page size and margins, a header and footer with page numbers, merge, watermark, form filling, text extraction, PDF to image, a digital signature, PDF/A output, an ASP.NET Core endpoint and a Linux Docker deployment. A task a library cannot do is marked not supported, with a link to the vendor page that says so, instead of being left blank.

Each sample is built and run, and a checker opens the output: the PDF must open, have the expected number of pages and contain the expected text. Licences, prices, platforms and engine versions on each library page link to the vendor's own page or the NuGet package, with the date they were checked.

The ten: ABCpdf, Docotic.Pdf, IronPDF, iText with pdfHTML, PDFsharp / MigraDoc, Playwright, PuppeteerSharp, QuestPDF, SelectPdf and wkhtmltopdf (through the Haukcode.WkHtmlToPdfDotNet wrapper).

How the harness measures

Each library runs behind a small adapter program, and one runner drives them all over the same 18 test pages: Bootstrap layouts, an invoice, web fonts, grid and flexbox, a chart drawn by JavaScript, lazy-loaded and large images, right-to-left and CJK text, a long document and more.

Speed: 9 conversions per page in a warm process after a discarded warm-up, with the libraries interleaved (A, B, C, A, B, C…) so machine drift is spread out. Medians are reported, and the summary uses the geometric mean over the pages every HTML library converted.
Throughput: conversions a minute for 60 seconds at 1, 4 and 8 at once, through the synchronous API and the asynchronous one.
Memory: the proportional set size of the library's whole process tree, so browser-based engines with many processes are counted fairly, plus 1,000 conversions in one process to see whether memory grows.
Output: 48 content checks (text present, nothing cut off, fonts embedded, page numbers, bookmarks, form fields, encryption, isolation between conversions) and fidelity: each PDF is compared, tile by tile, with a Chrome screenshot of the same page using SSIM, with evaluation watermarks masked.
Standards: every PDF/A and PDF/UA level a library offers is requested and validated twice by veraPDF; PDF/X-1a, which veraPDF does not cover, is checked structurally.
Deployment: each published app runs in mcr.microsoft.com/dotnet/runtime:8.0 as root and as a non-root user, first with nothing added, then following the vendor's own Docker instructions.

Windows and Linux on one machine

The run used one machine (Intel Core Ultra 9 275HX, 24 logical cores): Windows, and Ubuntu 24.04 under WSL2 on the same hardware. That keeps the two operating systems comparable with each other, but WSL2 is not a separate Linux server, and your production machine is not this one. Treat the numbers as relative, not as capacity planning.

Different libraries win different measures

There is no overall score, because the winners change from one measure to the next:

Fastest HTML to PDF per page on Windows: iText (183 ms), just ahead of IronPDF (186 ms).
Fastest per page on Linux: Docotic.Pdf (107 ms), with Playwright at 108 ms.
Most conversions a minute with 8 at once: IronPDF on Windows (1,735), SelectPdf on Linux (2,597).
Least memory growth over 1,000 conversions: iText on both systems.
Smallest publish size: PDFsharp (2.1 MB on linux-x64).
Most content checks passed, closest to Chrome, most PDF/A, PDF/UA and PDF/X levels valid, and most PDF tasks offered: SelectPdf (46 of 48, 0.984, 17 of 17, 11 of 11).

Some results are about deployment rather than speed. On the plain .NET runtime image, SelectPdf, iText, PDFsharp and QuestPDF ran as root and as a non-root user with nothing installed; ABCpdf, Docotic.Pdf and IronPDF needed the OS packages from their own instructions; Playwright, PuppeteerSharp and wkhtmltopdf did not run on the plain image.

The full tables, with every page and every failed check, are on the results page linked below. If you only need documents built in C# without HTML, QuestPDF or PDFsharp may be all you need; if you already run Playwright for end-to-end tests, printing with it may be enough. The point of publishing everything is that you can make that call yourself. The same summary, with each library's licence and price, is on our C# PDF libraries compared page.

Re-run it

The harness needs the .NET 8 SDK, Python 3 and veraPDF. Libraries that need a trial key read it from an environment variable and are skipped without one.

./run.sh             # Linux

./run.ps1            # Windows
./run.ps1 -Linux     # Windows, then the same run inside WSL

A full run takes about half an hour per operating system on an otherwise idle machine. The published Linux results came from the second Windows command, which runs the same harness inside WSL.

Limitations

One machine and one run per operating system; Linux is WSL2, not a separate host.
Commercial libraries run on their free trial or evaluation; watermarks are masked before images are compared.
Each library is configured the way its vendor documents. If we got your library's setup wrong, open an issue or a pull request: the adapter code for every library is in the harness repository, and corrections are welcome.
The benchmark is maintained by a vendor whose library is included. Public code and raw data make it checkable; they do not make it independent.

SelectPdf in 2026: A Cross-Platform .NET PDF Library for Windows, Linux and macOS

Florentin Badea — Fri, 16 Oct 2026 08:01:57 +0000

I'm the founder of SelectPdf. For most of its twelve years, our .NET PDF library ran on Windows only. If you needed HTML to PDF on Linux or macOS, we pointed you to our REST API. Articles written before October 2026 describe it that way, and for the library of that time they were right.

In October 2026 that changed. Version 26.4 introduced SelectPdf.Universal, a new edition of the library that runs locally on Windows, Linux and macOS. Version 26.5, released ten days later, added a remote engine that also takes it to Alpine Linux and Kubernetes. This article walks through what the library looks like now, with code.

Where it runs

SelectPdf.Universal runs on:

Windows x64 and x86
Linux x64 and ARM64
macOS on Apple Silicon
Docker containers, and through the remote engine, Alpine Linux and Kubernetes

It targets .NET 8, .NET 10 and .NET Standard 2.0, so it works on everything from .NET Framework 4.6.1 to the current .NET releases. We have verified it on Azure App Service, Azure Functions, AWS Lambda and Google Cloud Run.

Installing takes one package for the platform you deploy to:

dotnet add package SelectPdf.Universal.Linux

The others are SelectPdf.Universal.Windows, SelectPdf.Universal.Linux.Arm64 and SelectPdf.Universal.MacOS. Each one installs the library together with the rendering engine for its platform. A build that targets several platforms references SelectPdf.Universal plus one SelectPdf.Universal.Native.<rid> package per runtime instead.

On Linux, the engine package brings the libraries Chromium needs, so a Docker image needs no apt-get step:

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -f net10.0 -o /out

FROM mcr.microsoft.com/dotnet/runtime:10.0-noble
# no apt-get: the Chromium closure ships in SelectPdf.Universal.Native.linux-x64
WORKDIR /app
COPY --from=build /out ./
ENTRYPOINT ["dotnet", "/app/PdfSample.dll"]

The native packages need glibc 2.30 or later (Debian 11+, Ubuntu 20.04+, RHEL 9+). For musl-based images such as Alpine, there is the remote engine, below.

HTML to PDF

The API is the one SelectPdf users already know, in a new namespace:

using SelectPdf.Universal;

HtmlToPdf converter = new HtmlToPdf();

// A4 portrait with 20 mm margins (margins are in points: 20 mm = 57 pt)
converter.Options.PdfPageSize = PdfPageSize.A4;
converter.Options.PdfPageOrientation = PdfPageOrientation.Portrait;
converter.Options.MarginTop = 57;
converter.Options.MarginBottom = 57;
converter.Options.MarginLeft = 57;
converter.Options.MarginRight = 57;

// a web page, by URL
PdfDocument page = converter.ConvertUrl("https://selectpdf.com");
page.Save("webpage.pdf");
page.Close();

The rendering engine is Chromium, so flexbox, grid, web fonts and current JavaScript render the way they do in the browser. There is one engine, so there is no engine to choose.

Async, with cancellation

The library has a Task-based API: ConvertUrlAsync and ConvertHtmlStringAsync on the HTML converter, async methods on the HTML to image converter, and AddAsync for HTML placed into an existing document. Each takes a CancellationToken:

using SelectPdf.Universal;

// in a web app or service: await the conversion, and give up after 30 seconds
using var timeout = new CancellationTokenSource(TimeSpan.FromSeconds(30));

HtmlToPdf converter = new HtmlToPdf();
PdfDocument doc = await converter.ConvertUrlAsync("https://selectpdf.com", timeout.Token);

byte[] pdf = doc.Save();   // the PDF as bytes, for a response or a database
doc.Close();

Up to eight conversions run in parallel by default, and the rest queue in arrival order. Version 26.5 made parallel conversions much faster.

New in 26.4: beyond HTML to PDF

Word to PDF. docx, doc, rtf, txt, WordML, HTML and Markdown files convert directly, on every platform:

using SelectPdf.Universal;

WordToPdf converter = new WordToPdf();
converter.Options.PageSetup = WordPageSetup.Document;   // each page keeps its Word size
converter.Options.Bookmarks = WordBookmarks.Headings;   // the PDF outline comes from the headings

PdfDocument doc = converter.ConvertFile("report.docx");
doc.Save("report.pdf");
doc.Close();

Redaction. Text, images and form fields are removed from the file, not just covered. You can redact by area, by exact text or by regular expression:

using System.Text.RegularExpressions;
using SelectPdf.Universal;

var redactor = new PdfRedactionManager();
redactor.Load("statement.pdf");
redactor.AddRedaction(new Regex(@"\d{4}-\d{4}-\d{4}-\d{4}"));   // card numbers
redactor.OverlayText = "REDACTED";
redactor.Redact();
redactor.Save("statement-redacted.pdf");
redactor.Close();

Signature validation, with trust and revocation checks, next to signing.

Standards. Accessible PDF/UA-1 and PDF/UA-2 output, on new, converted and loaded documents; PDF/A-4, 4e and 4f archiving; and ZUGFeRD / Factur-X electronic invoices. New documents are encrypted with AES-256 by default.

New in 26.5: the remote engine

The library can hand its conversions to an engine running in a container on another machine. Set the rendering engine and point the library at the engine's address:

using SelectPdf.Universal;

// convert in the SelectPdf engine container instead of on this machine
GlobalProperties.RenderingEngine = RenderingEngine.ChromiumRemote;
GlobalProperties.EngineEndpoint = "http://selectpdf-engine:8080";

HtmlToPdf converter = new HtmlToPdf();
PdfDocument doc = converter.ConvertUrl("https://selectpdf.com");
doc.Save("output.pdf");
doc.Close();

HTML to PDF, HTML to image, PDF to text and PDF to image then run in the engine container, and the application needs no native package at all. That is what brings SelectPdf to Alpine Linux and other musl-based systems. The engine image is published for linux/amd64 and linux/arm64 as ghcr.io/selectpdf/engine, with a Helm chart, and the documentation has tested setups for Docker Compose, Kubernetes, Azure Container Apps, Amazon ECS and Google Cloud Run.

Also new in 26.5

Tables of contents with page numbers, built while the HTML converts. The library can add leaders and page numbers to a table of contents the page already has, write one into the page from its headings, or insert separate table of contents pages:

HtmlToPdf converter = new HtmlToPdf();
converter.Options.TableOfContents.Mode = PdfTableOfContentsMode.GeneratePages;
converter.Options.TableOfContents.HeadingSelectors = new[] { "h1", "h2" };
PdfDocument doc = converter.ConvertHtmlString(html);

Fillable PDF forms from HTML forms. With converter.Options.CreateFormFields = true, the text inputs, check boxes, radio buttons, drop-down lists and text areas of the page become PDF form fields, with their values, labels and options.

Signing with keys the library never sees. PKCS#11 tokens, smart cards and HSMs, the certificate store, or a remote signing service, with long-term validation (PAdES B-LT) and SHA-384 or SHA-512:

// the key stays on the token; the library sends it the digest to sign
var signer = new PdfPkcs11Signer("path/to/pkcs11-library", pin, "token label", "key label");
var signature = new PdfDigitalSignatureElement(50, 50, 240, 80, signer);
signature.DigestAlgorithm = PdfSignatureDigest.SHA384;
signature.EnableLtv = true;   // embed the revocation data (PAdES B-LT)
doc.Pages[0].Add(signature);
doc.Save("signed.pdf");

More archiving levels: PDF/A-1a, PDF/A-2a and PDF/A-2u. Smaller files from pages with large photos, and text search in Chinese, Japanese, Korean, Hindi, Thai and Arabic.

For projects still on wkhtmltopdf

wkhtmltopdf is no longer maintained. Four new open-source packages, SelectPdf.Compat.DinkToPdf and SelectPdf.Compat.WkHtmlToPdfDotNet, each with a .Licensed version, keep the API of the DinkToPdf and Haukcode.WkHtmlToPdfDotNet wrappers. Existing converter code builds as it is and renders with Chromium. They are MIT licensed, on GitHub.

The free Community Edition

SelectPdf.HtmlToPdf.Universal is free, with no watermark, and converts HTML to PDF on the same platforms, up to 5 pages per document. It has the same one-package installs (SelectPdf.HtmlToPdf.Windows, .Linux, .Linux.Arm64 and .MacOS) and supports the remote engine. Your code can check whether the page limit cut a document:

PdfDocument doc = converter.ConvertHtmlString(html);
if (converter.ConversionResult.PdfPageCountBeforeLimit > converter.ConversionResult.PdfPageCount)
    Console.WriteLine("the 5-page limit cut this document");

The classic library

The classic SelectPdf library for Windows is still maintained and receives selected updates; it is version 26.5 too. It remains the choice for .NET Framework 2.0 and later, and for projects that use the WebKit or Blink engines.

Moving an existing project to SelectPdf.Universal is mostly mechanical: new packages, a new namespace, and SelectPdf's own drawing types in place of System.Drawing. 82% of the classic library's public types and members carry over unchanged apart from the namespace, and the migration guide lists every change.

Licensing

One perpetual license per developer, from $499, covers both SelectPdf.Universal and the classic Windows library.

HTML to PDF in a .NET Docker container, with no apt-get

Florentin Badea — Mon, 05 Oct 2026 13:29:13 +0000

Disclosure: I work on SelectPdf, the library used in this article. It's a commercial library with a free Community Edition; both are covered at the end.

If you've ever generated PDFs from HTML in a Linux container, you probably know the drill: a headless browser needs a long list of shared libraries, so the Dockerfile grows an apt-get install line with twenty-odd packages, then fonts, then sometimes --no-sandbox or a bigger --shm-size. Every base-image update is a chance for that list to break.

This article builds a small ASP.NET Core service that converts web pages and HTML to PDF in a stock .NET runtime container, with none of that. It uses SelectPdf.Universal, which renders with Chromium and ships the engine, with everything it needs, inside a NuGet package.

What we're building

A minimal API with two endpoints:

GET /pdf?url=… returns any web page as a PDF
POST /pdf with an HTML body returns that HTML as a PDF

1. The project

Create a web project and add two packages: the library, and the native engine for the platform the container runs on.

dotnet new web -n PdfService
cd PdfService
dotnet add package SelectPdf.Universal
dotnet add package SelectPdf.Universal.Native.linux-x64

The native package is the part that makes the container story simple: it carries the complete Chromium shared-library closure, including the modules Chromium loads at run time for HTTPS. dotnet publish copies it into the output, so the image needs nothing else.

2. The code

Replace Program.cs:

using SelectPdf.Universal;

var app = WebApplication.CreateBuilder(args).Build();

// GET /pdf?url=https://example.com  ->  the page as a PDF download
app.MapGet("/pdf", async (string url, CancellationToken ct) =>
{
    var converter = new HtmlToPdf();
    PdfDocument doc = await converter.ConvertUrlAsync(url, ct);
    byte[] pdf = doc.Save();
    doc.Close();
    return Results.File(pdf, "application/pdf", "page.pdf");
});

// POST /pdf with an HTML body  ->  that HTML as a PDF
app.MapPost("/pdf", async (HttpRequest request, CancellationToken ct) =>
{
    string html = await new StreamReader(request.Body).ReadToEndAsync(ct);
    var converter = new HtmlToPdf();
    PdfDocument doc = await converter.ConvertHtmlStringAsync(html, ct);
    byte[] pdf = doc.Save();
    doc.Close();
    return Results.File(pdf, "application/pdf", "document.pdf");
});

app.Run();

The async methods take a CancellationToken, so a client that disconnects cancels its conversion. doc.Save() with no arguments returns the PDF as a byte array; doc.Save("file.pdf") writes it to disk instead.

3. The Dockerfile

A standard multi-stage build. Note what's not in it:

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish PdfService.csproj -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080
USER app
ENTRYPOINT ["dotnet", "PdfService.dll"]

No apt-get, no fonts step, no Xvfb. The engine renders headless, so there's no display server. It also runs as the image's built-in non-root app user: when the app is published on Linux, as it is inside this build, the native package makes the engine files readable and executable for every user.

Add a .dockerignore so local build output stays out of the image:

bin/
obj/

4. Build and run

docker build -t pdfservice .
docker run --rm -p 8080:8080 pdfservice

A plain docker run: no --no-sandbox, no added capabilities, no privileged mode, no GPU and no --shm-size. Docker's default 64 MB of shared memory is enough.

Try it:

curl -o page.pdf "http://localhost:8080/pdf?url=https://example.com"

curl -X POST -H "Content-Type: text/html" \
     --data-binary "<h1>Hello from Docker</h1>" \
     -o hello.pdf http://localhost:8080/pdf

5. Fonts for every language

Base images ship with no fonts at all. The library carries the Liberation fonts, so Latin, Greek and Cyrillic text renders correctly out of the box. For anything else (Chinese, Japanese, Korean, Arabic, Hebrew, Hindi, Thai and more, plus color emoji), add one package:

dotnet add package SelectPdf.Universal.Fonts

It copies the Noto fonts into your publish output at build time, so nothing gets installed in the image. With it referenced, this renders correctly in the same container:

curl -X POST -H "Content-Type: text/html; charset=utf-8" \
     --data-binary "<p>中文 日本語 العربية 😀</p>" \
     -o languages.pdf http://localhost:8080/pdf

6. ARM64, and building on a Mac

For ARM64 containers (AWS Graviton, Ampere, or Docker on an Apple Silicon Mac), reference SelectPdf.Universal.Native.linux-arm64 instead of linux-x64. Nothing else changes: the mcr.microsoft.com/dotnet tags are multi-architecture, so the same FROM lines pick the right image.

One thing that catches people on a Mac: Docker Desktop runs Linux containers, so the image needs linux-arm64, not osx-arm64. The macOS package is for apps running natively on macOS.

What works, and what doesn't

Base images. Any glibc-based .NET image. The engines need glibc 2.30 or newer, which covers Ubuntu 20.04+, Debian 11+ and RHEL 9+. Verified end to end, with a real HTTPS page and no packages installed: Debian 12, Ubuntu 22.04, Ubuntu 24.04, and Amazon Linux 2023 through a self-contained publish.

Not supported: Alpine. The native engines need glibc, and Alpine uses musl. Stay on the default Debian or Ubuntu based tags.

Resources. Chromium-based rendering likes CPU and memory. Plan for at least 1 core and 2 GB of RAM per container, and 2+ cores if you convert a lot under load.

Windows containers work too, on Windows Server Core, but they need a step to install the core Windows fonts. If Windows isn't a requirement, Linux containers are smaller and simpler.

Licensing

SelectPdf.Universal is commercial. Without a license the output carries a trial watermark; with one, set GlobalProperties.LicenseKey at startup. Licenses are perpetual and per developer, from $499, and one license covers both SelectPdf.Universal and the classic Windows library.
SelectPdf.HtmlToPdf.Universal is the free Community Edition: HTML to PDF only, free for commercial use, no watermark, up to 5 pages per document. The code in this article runs unchanged with it: reference SelectPdf.HtmlToPdf.Universal instead of SelectPdf.Universal, keep the same native package, and longer documents stop at five pages.

Wrapping up

The whole container story comes down to two dotnet add package lines and an ordinary Dockerfile. The documentation has more: a Docker deployment guide with Windows containers and batch jobs, and step-by-step pages for Azure Container Apps, AWS Lambda and Google Cloud Run.

Cross-platform library: https://selectpdf.com/pdf-library-cross-platform/
Launch post (what's new in 26.4): https://selectpdf.com/selectpdf-universal-our-new-flagship-net-pdf-library-on-linux-macos-and-docker/

If you try it and hit something this article doesn't cover, let me know in the comments.

HTML to PDF in C#: The Complete Guide

Florentin Badea — Tue, 07 Jul 2026 15:39:39 +0000

This is a complete, hands-on guide to converting HTML to PDF in C# with the SelectPdf library for .NET. It works up from a three-line conversion to a production-ready workflow: every one of the 19 code steps is a full, compiling example taken straight from this project and rendered with the Chromium engine, so the code you copy is code that actually runs. Along the way you will build a real invoice from a data model, render complex CSS and paginating tables, control layout, handle dynamic and authenticated pages, secure and archive your output, integrate with ASP.NET Core, and finish with notes on running in production and troubleshooting.

Getting started

Add the SelectPdf packages, then build and run:

dotnet add package Select.Pdf.NetCore
dotnet add package Select.Pdf.NetCore.Chromium.Windows
dotnet run

Running the project writes each result PDF to output/ and the preview images shown below into images/.

Part 1 - Getting started

Convert an HTML string to PDF
Convert a URL to PDF
Convert a local HTML file to PDF

Part 2 - Build a real document

Build an invoice from a template
Render complex HTML that paginates

Part 3 - Control the page layout

Set page size, orientation and margins
Add headers and footers with page numbers
Use HTML for headers and footers
Generate bookmarks from HTML headings
Produce a single-page PDF
Add a watermark to every page

Part 4 - Dynamic and remote content

Wait for JavaScript-rendered content
Inject custom CSS and run a script
Control the browser viewport width
Send HTTP headers and cookies

Part 5 - Secure, archive, integrate

Set the document properties
Password-protect and restrict permissions
Create an archivable PDF/A-3 document
Generate a PDF in ASP.NET Core

Part 6 - Run it in production

Running in production
Troubleshooting

FAQ

Frequently asked questions

Part 1 - Getting started

1. Convert an HTML string to PDF

The simplest conversion: render a raw HTML string into a PDF document in a few lines of code.

// Create the HTML to PDF converter and select the Chromium (CEF) engine.
HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Convert a raw HTML string into a PDF document.
PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Hello, SelectPdf!</h1>" +
    "<p>This PDF was generated from an HTML string in C#.</p>");

// Save the document to disk, then release the native resources.
doc.Save(outputPdf);
doc.Close();

Output:

2. Convert a URL to PDF

Point the converter at any public web address and capture the rendered page as a PDF.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Convert a live web page to a PDF document.
PdfDocument doc = converter.ConvertUrl("https://www.selectpdf.com");

doc.Save(outputPdf);
doc.Close();

Output:

3. Convert a local HTML file to PDF

Render an HTML file from disk - together with its local CSS and images - into a PDF.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// ConvertUrl also accepts a local file path; relative CSS and images
// referenced by the file are resolved automatically.
PdfDocument doc = converter.ConvertUrl(htmlFile);

doc.Save(outputPdf);
doc.Close();

Output:

Part 2 - Build a real document

4. Build an invoice from a template

Turn a C# data model into a styled, real-world invoice: branded header, a line-item table, VAT totals and a page-numbered footer.

// 1) Your data - normally from a database or an order.
var items = new[]
{
    new LineItem { Description = "SelectPdf Developer License", Qty = 1, UnitPrice = 499m },
    new LineItem { Description = "Priority Support (1 year)",    Qty = 1, UnitPrice = 199m },
    new LineItem { Description = "On-site training (per day)",    Qty = 2, UnitPrice = 900m },
};

// 2) Render the data into an HTML template (see BuildInvoiceHtml in the source).
string html = BuildInvoiceHtml("INV-1042", items);

// 3) Convert to PDF, adding a footer with page numbers.
HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;
converter.Options.MarginTop = 20;
converter.Options.MarginBottom = 30;

converter.Options.DisplayFooter = true;
converter.Footer.Height = 28;
PdfTextSection pageNo = new PdfTextSection(0, 8,
    "Invoice INV-1042 - page {page_number} of {total_pages}",
    new Font("Arial", 8));
pageNo.HorizontalAlign = PdfTextHorizontalAlign.Right;
converter.Footer.Add(pageNo);

PdfDocument doc = converter.ConvertHtmlString(html);
doc.Save(outputPdf);
doc.Close();

Output:

5. Render complex HTML that paginates

Prove the engine handles modern CSS - grid layout and a live web font - plus a long table whose header repeats on every page.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Give the web font a moment to download before the page is captured.
converter.Options.MinPageLoadTime = 2;

// The report uses CSS grid, a Google web font, and a 30-row table.
// The table header repeats on every page (thead { display: table-header-group })
// and rows are kept whole (page-break-inside: avoid) - all controlled from CSS.
PdfDocument doc = converter.ConvertHtmlString(BuildReportHtml());

doc.Save(outputPdf);
doc.Close();

Output:

Part 3 - Control the page layout

6. Set page size, orientation and margins

Control the physical page: choose A4, switch to landscape, and set the page margins.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Page setup (margins are expressed in points; 72 points = 1 inch).
converter.Options.PdfPageSize = PdfPageSize.A4;
converter.Options.PdfPageOrientation = PdfPageOrientation.Landscape;
converter.Options.MarginLeft = 36;
converter.Options.MarginRight = 36;
converter.Options.MarginTop = 36;
converter.Options.MarginBottom = 36;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>A4 Landscape</h1>" +
    "<p>This page uses a custom size, orientation and half-inch margins.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

7. Add headers and footers with page numbers

Draw a repeating header on every page and a footer that shows "Page X of Y".

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Enable and populate the header.
converter.Options.DisplayHeader = true;
converter.Header.Height = 40;
PdfTextSection headerText = new PdfTextSection(
    0, 12, "SelectPdf Tutorial", new Font("Arial", 10, FontStyle.Bold));
headerText.HorizontalAlign = PdfTextHorizontalAlign.Left;
converter.Header.Add(headerText);

// Enable and populate the footer with page numbering tokens.
converter.Options.DisplayFooter = true;
converter.Footer.Height = 40;
PdfTextSection footerText = new PdfTextSection(
    0, 12, "Page {page_number} of {total_pages}", new Font("Arial", 8));
footerText.HorizontalAlign = PdfTextHorizontalAlign.Right;
converter.Footer.Add(footerText);

PdfDocument doc = converter.ConvertUrl("https://www.selectpdf.com");

doc.Save(outputPdf);
doc.Close();

Output:

8. Use HTML for headers and footers

Build a fully styled header or footer from an HTML fragment instead of plain text.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Render the header from an HTML fragment so it can be fully styled with CSS.
converter.Options.DisplayHeader = true;
converter.Header.Height = 50;

PdfHtmlSection header = new PdfHtmlSection(
    "<div style='font-family:Arial;color:#b45309;font-size:18px;" +
    "border-bottom:2px solid #b45309;padding:6px 0;'>Acme Corporation</div>",
    string.Empty);
header.RenderingEngine = RenderingEngine.Chromium;
header.AutoFitHeight = HtmlToPdfPageFitMode.AutoFit;
converter.Header.Add(header);

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Report body</h1><p>The header above is rendered from HTML.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

9. Generate bookmarks from HTML headings

Turn the document's headings into a clickable PDF bookmarks (outline) tree.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Build PDF bookmarks from the elements matching these CSS selectors.
converter.Options.PdfBookmarkOptions.CssSelectors = new string[] { "h1", "h2" };

// Open the document with the bookmarks (outline) panel visible.
converter.Options.ViewerPreferences.PageMode = PdfViewerPageMode.UseOutlines;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Chapter 1</h1><p>Introduction.</p>" +
    "<h2>Section 1.1</h2><p>Details.</p>" +
    "<h1>Chapter 2</h1><p>More content.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

10. Produce a single-page PDF

Fit the whole document onto one continuous page with no page breaks - handy for receipts and tickets.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Produce one continuous page sized to the content, instead of paginating.
converter.Options.GenerateSinglePagePdf = true;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Single-page output</h1>" +
    "<p>Section one.</p><p>Section two.</p><p>Section three.</p>" +
    "<p>All content stays on a single, taller page with no page breaks.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

11. Add a watermark to every page

Stamp a semi-transparent text watermark - such as CONFIDENTIAL or DRAFT - behind the content of every page.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Draft report</h1><p>Every page of this document carries a watermark.</p>");

// Draw a large, light "CONFIDENTIAL" behind the content of every page,
// using a background template that repeats on all pages.
PdfFont font = doc.AddFont(PdfStandardFont.Helvetica);
font.Size = 50;

RectangleF pageRect = doc.Pages[0].ClientRectangle;
PdfTemplate template = doc.AddTemplate(pageRect);
template.Background = true;

PdfTextElement watermark = new PdfTextElement(
    0, pageRect.Height / 2 - 30, pageRect.Width, "CONFIDENTIAL", font);
watermark.ForeColor = Color.FromArgb(210, 210, 210);
watermark.HorizontalAlign = PdfTextHorizontalAlign.Center;
template.Add(watermark);

doc.Save(outputPdf);
doc.Close();

Output:

Part 4 - Dynamic and remote content

12. Wait for JavaScript-rendered content

Give client-side scripts time to run so dynamic content is captured instead of a half-loaded page.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Give client-side scripts time to run before the page is captured (seconds).
converter.Options.MinPageLoadTime = 2;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Dynamic content</h1>" +
    "<p id='status'>Loading...</p>" +
    "<script>setTimeout(function(){" +
    "document.getElementById('status').innerHTML = 'Loaded by JavaScript!';" +
    "}, 800);</script>");

doc.Save(outputPdf);
doc.Close();

Output:

13. Inject custom CSS and run a script

Restyle the page with your own CSS and execute JavaScript after load, without touching the source HTML.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Inject additional CSS into the page before rendering.
converter.Options.CustomCSS =
    "body { font-family: Arial; background: #fef3c7; }" +
    "h1 { color: #b45309; }";

// Run JavaScript after the page has loaded (Chromium/Blink only).
converter.Options.PostLoadingScript =
    "document.body.insertAdjacentHTML('beforeend', '<p>Added by script.</p>');";

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Custom styled page</h1>" +
    "<p>The amber background and heading color come from injected CSS.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

14. Control the browser viewport width

Set the virtual browser width the HTML is laid out at, then shrink oversized layouts to fit the PDF page.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Lay the HTML out at a fixed 1200px browser width...
converter.Options.WebPageWidth = 1200;
converter.Options.WebPageFixedSize = true;

// ...then shrink it so the wide layout fits the PDF page width.
converter.Options.AutoFitWidth = HtmlToPdfPageFitMode.ShrinkOnly;

PdfDocument doc = converter.ConvertHtmlString(
    "<div style='width:1200px;background:#e0f2fe;padding:24px'>" +
    "<h1>Wide layout</h1>" +
    "<p>Rendered at a 1200px viewport, then shrunk to fit the page.</p></div>");

doc.Save(outputPdf);
doc.Close();

Output:

15. Send HTTP headers and cookies

Attach custom request headers and cookies to reach authenticated or localized pages.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Attach custom request headers (e.g. language, bearer token) and cookies.
converter.Options.HttpHeaders.Add("Accept-Language", "en-US");
converter.Options.HttpCookies.Add("session", "demo-cookie-value");

PdfDocument doc = converter.ConvertUrl("https://www.selectpdf.com");

doc.Save(outputPdf);
doc.Close();

Output:

Part 5 - Secure, archive, integrate

16. Set the document properties

Fill in the PDF title, author, subject and keywords shown in the viewer and used by search indexes.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Quarterly Report</h1><p>Prepared for Acme Corporation.</p>");

// These appear in the viewer's "Document Properties" dialog and in search indexes.
doc.DocumentInformation.Title = "Quarterly Report";
doc.DocumentInformation.Author = "SelectPdf";
doc.DocumentInformation.Subject = "Q3 financial results";
doc.DocumentInformation.Keywords = "report, quarterly, finance";
doc.DocumentInformation.CreationDate = DateTime.Now;

doc.Save(outputPdf);
doc.Close();

Output:

17. Password-protect and restrict permissions

Encrypt the PDF with an owner password and disable copying and editing.

HtmlToPdf converter = new HtmlToPdf();
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Encrypt with an owner password and restrict what readers may do.
// (Set UserPassword as well to also require a password just to open the file.)
converter.Options.SecurityOptions.OwnerPassword = "owner-secret";
converter.Options.SecurityOptions.CanPrint = true;
converter.Options.SecurityOptions.CanCopyContent = false;
converter.Options.SecurityOptions.CanEditContent = false;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Confidential</h1><p>Copying and editing are disabled on this document.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

18. Create an archivable PDF/A-3 document

Emit a PDF/A-3B file suitable for long-term archiving and compliance.

HtmlToPdf converter = new HtmlToPdf();

// PDF/A (and tagged/accessible) output requires the Chromium engine.
converter.Options.RenderingEngine = RenderingEngine.Chromium;

// Emit a PDF/A-3B document suitable for long-term archiving.
converter.Options.PdfStandard = PdfStandard.PdfA3B;

PdfDocument doc = converter.ConvertHtmlString(
    "<h1>Archivable document</h1>" +
    "<p>Saved as PDF/A-3B for long-term archiving and compliance.</p>");

doc.Save(outputPdf);
doc.Close();

Output:

19. Generate a PDF in ASP.NET Core

Build the PDF in a controller action and stream it straight to the browser as a downloadable file.

// In an ASP.NET Core app, generate the PDF inside a controller action and stream it back.
public sealed class InvoiceController : ControllerBase
{
    [HttpGet("/invoice/{id:int}")]
    public IActionResult Get(int id)
    {
        HtmlToPdf converter = new HtmlToPdf();
        converter.Options.RenderingEngine = RenderingEngine.Chromium;

        PdfDocument doc = converter.ConvertHtmlString(
            $"<h1>Invoice #{id}</h1><p>Thank you for your order.</p>");

        // Save straight to a byte array - no temp file needed.
        byte[] pdf = doc.Save();
        doc.Close();

        // Return it as a downloadable file (omit the file name to show it inline).
        return File(pdf, "application/pdf", $"invoice-{id}.pdf");
    }
}

Output:

Part 6 - Run it in production

20. Running in production

SelectPdf runs entirely in-process and is Windows-only (x86 and x64) - there is no Linux or macOS build, and the host needs full trust. Factor that into your hosting choice before you commit.

A converter instance is not thread-safe: create one HtmlToPdf per conversion rather than sharing one across threads, and cap parallelism with your own queue or semaphore - the library has no built-in concurrency limit.

Deployment - ship Select.Pdf.dll together with Select.Html.dep and Select.Tools.dep; for the Chromium engine also deploy its runtime folder (the Chromium.Windows package copies it on build).
Process bitness - match the package to the process or you get a BadImageFormatException. Under IIS, Enable 32-Bit Applications = True runs x86, False runs x64.
Memory - on 64-bit servers use the x64 package - it can allocate far more memory for image-heavy pages.
Timeouts - the default navigation timeout is 60 seconds; raise Options.MaxPageLoadTime for slow pages and use MinPageLoadTime to wait for late assets.
Licensing - set GlobalProperties.LicenseKey once at startup, before any conversion; the trial watermarks every page.
Untrusted HTML - disable scripts (Options.JavaScriptEnabled = false) and local file access (Options.DenyLocalFileAccess = true) when converting input you do not control.
Azure - App Service needs the Chromium engine (v26.2+, Basic plan or above); Virtual Machines and Cloud Services have no restrictions.

21. Troubleshooting

A handful of problems come up again and again - here is the quick fix for each.

Blank page, or images and CSS missing from an HTML string - pass a base URL: ConvertHtmlString(html, baseUrl) so relative URLs resolve.
Dynamic content missing - the page needs more time or a signal - set Options.MinPageLoadTime, or use WindowStatus / PostLoadingScript.
BadImageFormatException - the x86 or x64 package does not match the process bitness.
Could not find Select.Html.dep - copy Select.Html.dep and Select.Tools.dep next to Select.Pdf.dll.
Navigation timeout - the page is slower than 60s, the URL is not resolvable from the server, or a proxy is required - raise MaxPageLoadTime or set Options.ProxyOptions.
An image splits across two pages - set Options.KeepImagesTogether = true, or style the img with page-break-inside: avoid.
OutOfMemoryException - an image-heavy page - use the x64 package and optimize the images.

FAQ

22. Frequently asked questions

Is SelectPdf free? - The Community Edition (Select.HtmlToPdf) is free for HTML to PDF with a 5-page cap. This tutorial uses the commercial Select.Pdf library - a paid license with the full feature set and no page limit.
Does it run on Linux, macOS or in Docker? - No. The library is Windows-only (x86 and x64). To generate PDFs from Linux, host it on Windows or use the SelectPdf online HTML-to-PDF REST API instead.
Which rendering engine should I use? - Chromium (used throughout this tutorial) for modern HTML5, CSS3 and web fonts. WebKit is the embedded default with nothing extra to deploy; Blink is an alternative Chromium-based engine. Chromium and Blink each need their companion NuGet package.
How do I remove the trial watermark? - Set GlobalProperties.LicenseKey once at application startup, before any conversion. See .NET library pricing for license options.
Can it convert a page that requires login? - Yes - send authentication cookies or headers (see Send HTTP headers and cookies), or post form data with HttpPostParameters.
Is there a limit on the number of pages? - Not in the commercial library. The 5-page cap applies only to the free Community Edition.
Can I convert charts or content drawn by JavaScript? - Yes, with the Chromium engine. Give scripts time to run with Options.MinPageLoadTime, or wait for a signal via WindowStatus (see Wait for JavaScript-rendered content).
Is the converter thread-safe? - Use one HtmlToPdf instance per conversion and throttle concurrency yourself; see Running in production.

Conclusion

That is the full arc of HTML to PDF with SelectPdf - from a three-line string conversion to a real invoice, complex paginating layouts, security, archival compliance, ASP.NET Core integration and production hardening. Because the same Chromium engine powers every example, what you preview in the browser is what lands in the PDF. Start with a free trial, browse the full API reference, or try the live C# demo.

wkhtmltopdf is archived. A straight .NET migration guide (Windows, Linux, Docker and Azure)

Florentin Badea — Sun, 05 Jul 2026 06:53:30 +0000

Updated October 2026 for SelectPdf 26.4: the library now runs on Linux, in Docker and on macOS on Apple Silicon as well, through the new SelectPdf.Universal packages. The Linux sections below are rewritten accordingly.

If your .NET app still calls DinkToPdf, NReco.PdfGenerator, Rotativa, or WkHtmlToXSharp in production, you're shipping a wrapper around a binary that hasn't had a security patch in years — and one of its open holes is a CVSS 9.8.

wkhtmltopdf's repository has been frozen and read-only since January 2023, and the whole project org was archived by mid-2024. Development has stopped; nobody is accepting patches. The underlying QtWebKit engine forked from upstream around 2012 — no modern Flexbox, no Grid, no modern JavaScript, no ICU updates. And CVE-2022-35583 — an SSRF that lets an attacker reach your internal network by injecting an <iframe> pointing at an internal IP — sits at CVSS 9.8, unpatched, and permanently so.

If your app takes any user-influenced HTML and turns it into a PDF behind a public endpoint, that's not a "someday" cleanup. This post is the migration I'd actually run.

Disclosure: I work on SelectPdf, a .NET PDF library, and the code below is SelectPdf because that's what I can vouch for line by line. I'll be honest about where it fits and where it doesn't. The broader point stands no matter what you pick: stop wrapping the dead binary.

First: Windows, Linux or Docker?

I'm putting this at the top because it decides which packages you install, and nothing annoys an engineer more than finding it in paragraph 30. The good news: since version 26.4 there is a SelectPdf library for each case.

Linux, Docker, macOS on Apple Silicon — or any new project on modern .NET — use SelectPdf.Universal, the new flagship edition. It runs on Windows (x64, x86), Linux (x64, ARM64) and macOS on Apple Silicon, targets .NET 8 and .NET 10 plus .NET Standard 2.0, and renders with Chromium. You reference the library plus one native package per runtime you deploy to.
An existing Windows or .NET Framework app (IIS, a VM, Windows App Service) — the classic SelectPdf library is a direct NuGet reference with one API call, supports .NET Framework 2.0 and later, and keeps its four rendering engines. It is still maintained.
Not on .NET, or you want nothing to deploy at all — SelectPdf's Online REST API: your app POSTs HTML and gets back PDF bytes over HTTPS, from any OS and any language.

Linux is where wkhtmltopdf hurts most today (newer glibc/libssl combos crash it, and it's no one's job to fix), so it's worth being specific. The SelectPdf.Universal.Native.linux-x64 and linux-arm64 packages carry the shared libraries Chromium needs, so a stock .NET runtime image converts pages with no apt-get step, no X server and no special docker run flags. That was verified with real HTTPS conversions on Debian 12, Ubuntu 22.04, Ubuntu 24.04 and Amazon Linux 2023. Latin, Greek and Cyrillic text prints with the fonts built into the library; for other scripts (Arabic, Chinese, Japanese, Korean, Hindi, Thai and more) add the optional SelectPdf.Universal.Fonts package — also just a NuGet reference.

"Why not just use Playwright or PuppeteerSharp?"

Fair question, and for some teams that's the right call — they're free, cross-platform, and render with real Chromium. Here's the honest trade:

With Playwright/PuppeteerSharp you operate the browser yourself. You run a provisioning step (playwright install, or bundling the binaries) and version-manage Chromium; you own the headless browser's lifecycle (zombie processes are real under load); you write your own concurrency throttling; and you write and maintain the automation script. On Linux you also chase down the font and shared-library packages so text doesn't render as boxes. On Windows App Service specifically, a raw headless browser tends to fight the sandbox too — a similar restriction to the Win32k/GDI wall that bites wkhtmltopdf (more on that below).

Now the honest part, about what is not a difference: SelectPdf also ships a bundled Chromium (CEF) runtime of broadly similar size — so the disk/image footprint is roughly a wash. Chromium is Chromium. What differs is who provisions and babysits it. SelectPdf ships the matched runtime as a NuGet package that the build copies into your output automatically (no separate install step, no version drift), manages the browser for you, and caps parallelism through one built-in setting (MaximumConcurrentConversions) — all behind a single call that returns the PDF. On Linux the native package already carries the shared libraries, so there is nothing to apt-get. The engine is also built to run inside the App Service sandbox where a raw headless browser struggles. You don't write automation, and you don't provision a browser fleet.

And there's a scope difference that outlasts the migration: Playwright and Puppeteer only print HTML to PDF. The moment your requirements grow past "render this page" — merge the invoice with a cover sheet, stamp a watermark, fill an AcroForm, digitally sign it, encrypt it, or extract the text back out for search — you're bolting on a second PDF library (PdfSharp, iText, QuestPDF) and gluing two toolchains together. SelectPdf's commercial library does the rendering and that post-processing in one dependency: create PDFs from scratch, merge/split, stamp, fill and flatten forms, sign, encrypt, extract text and images, and emit tagged PDF/UA or PDF/A for accessibility and archival. (The free Community Edition is HTML→PDF only — these extras are the paid library.) If rendering HTML is genuinely all you'll ever do, that breadth doesn't matter and Puppeteer is fine. If you can feel a "can you also…" ticket coming, one library beats two.

If your team is happy operating headless Chrome directly and never needs more than print-to-PDF, Puppeteer is a perfectly defensible choice. Pick with eyes open.

(One more note on the "is it even alive?" question, since wkhtmltopdf just taught everyone to ask it: SelectPdf shipped **v26.4 in October 2026* — the release that added SelectPdf.Universal for Linux, Docker and macOS on Apple Silicon — and the packages sit at 23M+ NuGet downloads. Actively maintained, with a paid tier where a human answers.)*

What "archived" actually means for your stack

Most teams know wkhtmltopdf is "old" but haven't priced in the archive:

No more CVE patches. Ever. CVE-2022-35583 is filed, triaged, and will never be fixed upstream. Any SSRF reported after the repo froze lands in a read-only tracker.
QtWebKit is frozen near 2012. CSS Grid, container queries, modern JS, modern font features — anything your designers shipped in the last decade renders unreliably or not at all.
The .NET wrappers fix none of this. DinkToPdf, NReco.PdfGenerator, Rotativa.AspNetCore, WkHtmlToXSharp all P/Invoke into the same libwkhtmltox native binary. If wkhtmltopdf isn't patched, neither are they. (DinkToPdf itself hasn't shipped a release since 2017.)

The migration, in code

Here's a typical DinkToPdf setup — note the injected IConverter, which DinkToPdf requires as a singleton because the native lib can't be loaded repeatedly:

// Old: DinkToPdf
using DinkToPdf;
using DinkToPdf.Contracts;

public class InvoiceController : ControllerBase
{
    private readonly IConverter _converter;
    public InvoiceController(IConverter converter) => _converter = converter;

    [HttpGet("invoice/{id}")]
    public IActionResult Get(int id)
    {
        var html = RenderInvoiceHtml(id);

        var doc = new HtmlToPdfDocument
        {
            GlobalSettings = {
                PaperSize = PaperKind.A4,
                Orientation = Orientation.Portrait,
                Margins = new MarginSettings { Top = 20, Bottom = 20 }
            },
            Objects = { new ObjectSettings { HtmlContent = html } }
        };

        var pdf = _converter.Convert(doc);
        return File(pdf, "application/pdf", $"invoice-{id}.pdf");
    }
}

Same endpoint with SelectPdf.Universal — the same code runs on Windows, Linux and macOS on Apple Silicon:

// New: SelectPdf.Universal
using SelectPdf.Universal;

public class InvoiceController : ControllerBase
{
    [HttpGet("invoice/{id}")]
    public IActionResult Get(int id)
    {
        var html = RenderInvoiceHtml(id);

        var converter = new HtmlToPdf();
        converter.Options.PdfPageSize        = PdfPageSize.A4;
        converter.Options.PdfPageOrientation = PdfPageOrientation.Portrait;
        converter.Options.MarginTop = 20;
        converter.Options.MarginBottom = 20;

        PdfDocument doc = converter.ConvertHtmlString(html);
        try
        {
            byte[] bytes = doc.Save();   // parameterless Save() returns the PDF bytes
            return File(bytes, "application/pdf", $"invoice-{id}.pdf");
        }
        finally
        {
            doc.Close();
        }
    }
}

On the classic Windows library the code is the same apart from using SelectPdf; and one extra line to pick the engine: converter.Options.RenderingEngine = RenderingEngine.Chromium; (SelectPdf.Universal renders with Chromium only, so it needs no such line).

About that lifecycle change

You probably noticed the DI singleton is gone. That's deliberate, and it's the question a careful reviewer should ask: is new HtmlToPdf() per request safe?

Yes. Unlike DinkToPdf's converter, there's no "load the native lib exactly once" dance — you construct a converter per conversion. Parallelism is governed by a single knob, HtmlToPdfOptions.MaximumConcurrentConversions (default 8 in SelectPdf.Universal, 4 in the classic library), which you set once at startup, before the first conversion; requests beyond the limit queue for a slot rather than thrashing the box. So the mental model is: new freely per request, cap total concurrency globally. If you'd rather keep a DI registration for testability, register the converter as transient — it doesn't need to be a singleton. SelectPdf.Universal also has ConvertHtmlStringAsync and ConvertUrlAsync, with cancellation, if your controllers are async.

NuGet packages

# SelectPdf.Universal — Windows, Linux, Docker, macOS on Apple Silicon.
# The library, plus one native package per runtime you deploy to
# (win-x64, win-x86, linux-x64, linux-arm64, osx-arm64).

# Free Community Edition — HTML->PDF only, 5-page cap;
# no PDF post-processing (merge/split, forms, signing, encryption, extraction)
dotnet add package SelectPdf.HtmlToPdf.Universal
dotnet add package SelectPdf.Universal.Native.linux-x64

# Commercial library once you outgrow 5 pages (from $499, perpetual)
dotnet add package SelectPdf.Universal
dotnet add package SelectPdf.Universal.Native.linux-x64

# Optional on Linux: fonts for non-Latin scripts
dotnet add package SelectPdf.Universal.Fonts

# Classic library on Windows (.NET Framework 4.6.1+ and modern .NET;
# for .NET Framework 2.0/4.0 use Select.HtmlToPdf / Select.Pdf)
dotnet add package Select.HtmlToPdf.NetCore                    # free CE
dotnet add package Select.HtmlToPdf.NetCore.Chromium.Windows
dotnet add package Select.Pdf.NetCore                          # commercial
dotnet add package Select.Pdf.NetCore.Chromium.Windows

Reference several native packages if you build for several targets — developing on Windows and deploying to a Linux container is the common case. Be honest with yourself about that 5-page cap: it's free forever, but a typical multi-page invoice or report blows past it, so for real workloads the CE is effectively an evaluation and you'll want a license (pricing). One perpetual license covers both the classic and the Universal library. The classic packages still target net20 and net40 (Select.Pdf, Select.HtmlToPdf) and net461, net472 and netstandard2.0 (the .NetCore packages), so migrating a .NET Framework app doesn't force a TFM bump.

Migrating your wkhtmltopdf flags

The ConvertHtmlString call is the easy 20%. The part that actually took you an afternoon in wkhtmltopdf was the CLI flags — headers, footers, page numbers, margins. Here's the mapping so you're not reverse-engineering it (it is the same in both libraries):

wkhtmltopdf	SelectPdf
`--page-size A4`	`Options.PdfPageSize = PdfPageSize.A4`
`--orientation Landscape`	`Options.PdfPageOrientation = PdfPageOrientation.Landscape`
`--margin-top 20` (etc.)	`Options.MarginTop = 20` (`MarginBottom/Left/Right`)
`--header-html header.html`	`Options.DisplayHeader = true;` then `converter.Header.Add(new PdfHtmlSection(url))`
`--footer-html footer.html`	`Options.DisplayFooter = true;` then `converter.Footer.Add(...)`
`[page] / [topage]` footer tokens	`{page_number}` / `{total_pages}` in a `PdfTextSection`
`--print-media-type`	`Options.CssMediaType = HtmlToPdfCssMediaType.Print`

Footer with page numbers, end to end:

converter.Options.DisplayFooter = true;
converter.Footer.Height = 40;

var pageNo = new PdfTextSection(0, 10,
    "Page {page_number} of {total_pages}",
    PdfFont.CreateStandardFont(PdfStandardFont.Helvetica, 9));
pageNo.HorizontalAlign = PdfTextHorizontalAlign.Right;
converter.Footer.Add(pageNo);

(On the classic library, PdfTextSection takes a System.Drawing.Font instead, for example new System.Drawing.Font("Arial", 9). SelectPdf.Universal has its own font types because System.Drawing is Windows-only on current .NET.)

That — headers, footers, page numbering — all works in the free Community Edition too, within the 5-page cap.

The Azure App Service angle

This is the one I get asked about most, so I'll be explicit.

Azure App Service on Windows runs your app in a sandbox that blocks most User32/GDI32 (Win32k.sys) system calls — exactly what a GDI-based browser engine bundled in a .NET app needs. That's what makes wkhtmltopdf flaky there: P/Invoke load failures, missing GDI calls, font issues. Bundled headless-Chrome setups tend to struggle in the same sandbox too, for related reasons (process/GPU restrictions rather than GDI specifically).

SelectPdf's Chromium engine — on Chromium 154 as of v26.4 — is built to run inside that sandbox. With SelectPdf.Universal the same code runs on App Service and Azure Functions, on both Windows and Linux, on the Basic plan or above. One caveat worth knowing up front: on Windows, don't deploy with "Run From Package" (WEBSITE_RUN_FROM_PACKAGE) — the engine cannot load its libraries from the mounted package; Zip Deploy and Web Deploy are fine. The classic library runs on Windows App Service (Basic and above), and on Azure Functions when hosted on a Premium or App Service plan. From your code it's the same call you already saw:

var converter = new HtmlToPdf();

PdfDocument doc = converter.ConvertUrl("https://example.com/report");
doc.Save("report.pdf");
doc.Close();

No "but it works locally" Slack thread at 11pm.

Closing the SSRF loop

We opened on CVE-2022-35583, so let's not hand-wave the fix. Two things change when you migrate:

You get a kill-switch for local-file exfiltration. Set HtmlToPdfOptions.DenyLocalFileAccess = true per conversion, or GlobalProperties.ForceDenyLocalFileAccess = true process-wide, and file:// reads are blocked — shutting off the local-file-read half of the classic wkhtmltopdf attack. Both libraries have both switches.
The internal-IP SSRF half is a network problem, and the right answer depends on trust. If you convert genuinely untrusted, user-supplied HTML, don't render it on your own infrastructure next to your internal network at all — push it to the Online REST API, so the conversion runs off your infrastructure, away from your internal network. And unlike the archived binary, when a rendering-side issue is found, there's a maintained product that can actually ship a fix.

That's the real difference: not "SelectPdf is magically SSRF-proof," but "you get controls, isolation options, and someone who patches."

What to actually do this week

A pragmatic checklist:

grep the solution for DinkToPdf, NReco.PdfGenerator, Rotativa, WkHtmlToX, wkhtmltopdf. Every hit is a candidate.
Pick the package for where you deploy (see the top): SelectPdf.Universal for Linux, Docker and new projects; the classic library for an existing Windows or .NET Framework app; the Online API for anything else.
Pick the one endpoint that renders user-influenced HTML. Highest-risk surface; start there.
dotnet add package SelectPdf.HtmlToPdf.Universal + SelectPdf.Universal.Native.<rid> for each runtime you deploy to. Free, 5-page cap.
Port the converter call and your header/footer flags using the mapping above; run your existing tests; eyeball the output diff.
If layout shifts (it might — wkhtmltopdf has 2012-era quirks your CSS may lean on), the fix is almost always a CSS cleanup, not a converter tweak.
Past 5 pages, get a license — but validate output on the free build first.

If SelectPdf isn't right for your stack, still migrate. Anything maintained beats an archived 9.8. And if you try it and hit a snag, drop me a line — I read the inbox.

Try it:

Cross-platform library (Windows, Linux, Docker, macOS on Apple Silicon): selectpdf.com/pdf-library-cross-platform
Free Community Edition: selectpdf.com/community-edition
Live demo (paste any URL): selectpdf.com/demo-universal
Online API for any language: selectpdf.com/html-to-pdf-api
Docs, including Docker and Azure deployment: selectpdf.com/pdf-library
NuGet: SelectPdf.HtmlToPdf.Universal

If this was useful, follow — the next post is "Top 10 HTML-to-PDF Libraries for C# / .NET (2026): A Practical Comparison," a fair head-to-head of the real options in this space, including where SelectPdf isn't the right pick.

Stop your AI assistant from hallucinating PDF APIs: SelectPdf AI Tools

Florentin Badea — Wed, 01 Jul 2026 14:38:44 +0000

AI coding assistants are great at .NET boilerplate, but ask one to generate PDF code and it will happily invent a method that doesn't exist, or reach for a commercial feature while claiming it's in the free edition. The model is guessing from training data.

SelectPdf AI Tools fixes that. It's a free, open-source (MIT) set of Agent Skills that give your assistant accurate, version-matched knowledge of the SelectPdf .NET library — real API signatures, working code, and the gotchas that matter.

What's in it

A single Claude Code plugin with two skills:

selectpdf-lib-net — the full commercial Select.Pdf library: HTML→PDF, building/editing PDFs, merge/split, AcroForms, digital signatures, encryption, PDF→text/image, and accessible tagged PDF/UA-1 and PDF/A-3.
selectpdf-lib-htmltopdf-net — the free Community Edition (HTML→PDF).

Every sample is in C# and VB.NET, tracking SelectPdf v26.3.

Install in Claude Code

/plugin marketplace add selectpdf/ai-tools
/plugin install selectpdf@selectpdf

The right skill activates automatically when you ask it to work with PDFs in a .NET project.

Cursor, Copilot, Codex

The same knowledge ships in each tool's native format — Cursor .mdc rules, Copilot .instructions.md, and a Codex AGENTS.md guide. Drop the file into your repo and your assistant is up to speed.

It's all open source, so you can read exactly what your assistant is being told — and send a PR if you spot something. 👉 https://github.com/selectpdf/ai-tools

Want to see the library itself? Browse the online documentation or try the C# and VB.NET live demos.

DEV Community: Florentin Badea

SelectPdf vs IronPDF. An IronPDF alternative for .NET.

SelectPdf vs IronPDF in 2026, measured on Windows and Linux

SelectPdf vs IronPDF in 2026, measured on Windows and Linux

What changed in SelectPdf in 2026

The same task in both libraries

How it was measured

On Windows, IronPDF is faster

On Linux, SelectPdf is faster

Output quality

Docker

Price

Which one to choose

Limitations

Links

We compared 10 .NET PDF libraries on the same 14 C# tasks: here is the open benchmark

Why PDF library comparisons mislead

Fourteen tasks, one sample each

How the harness measures

Windows and Linux on one machine

Different libraries win different measures

Re-run it

Limitations

Links

SelectPdf in 2026: A Cross-Platform .NET PDF Library for Windows, Linux and macOS

Where it runs

HTML to PDF

Async, with cancellation

New in 26.4: beyond HTML to PDF

New in 26.5: the remote engine

Also new in 26.5

For projects still on wkhtmltopdf

The free Community Edition

The classic library

Licensing

Links

HTML to PDF in a .NET Docker container, with no apt-get

What we're building

1. The project

2. The code

3. The Dockerfile

4. Build and run

5. Fonts for every language

6. ARM64, and building on a Mac

What works, and what doesn't

Licensing

Wrapping up

HTML to PDF in C#: The Complete Guide

Getting started

Contents

Part 1 - Getting started

1. Convert an HTML string to PDF

2. Convert a URL to PDF

3. Convert a local HTML file to PDF

Part 2 - Build a real document

4. Build an invoice from a template

5. Render complex HTML that paginates

Part 3 - Control the page layout

6. Set page size, orientation and margins

7. Add headers and footers with page numbers

8. Use HTML for headers and footers

9. Generate bookmarks from HTML headings

10. Produce a single-page PDF

11. Add a watermark to every page

Part 4 - Dynamic and remote content

12. Wait for JavaScript-rendered content

13. Inject custom CSS and run a script

14. Control the browser viewport width

15. Send HTTP headers and cookies

Part 5 - Secure, archive, integrate

16. Set the document properties

17. Password-protect and restrict permissions

18. Create an archivable PDF/A-3 document

19. Generate a PDF in ASP.NET Core

Part 6 - Run it in production

20. Running in production

21. Troubleshooting

FAQ

22. Frequently asked questions

Conclusion