Getting Started with HiQPdf Chromium for .NET on Linux

HiQPdf Chromium for .NET offers a modern, simple, fast, flexible and powerful tool for creating complex and stylish PDF documents in .NET applications for Linux, using just a few lines of C# code and the integrated HTML to PDF Converter component.

The HTML to PDF converter uses Chromium as its rendering engine, capable of processing modern HTML, CSS and JavaScript in full compliance with the latest web standards and technologies.

HiQPdf Chromium for .NET runs natively on 64-bit Linux operating systems.

The .NET library targets .NET Standard 2.0, so it can be used in any .NET Core or .NET Framework application that supports this standard.

Depending on your Linux distribution and installed packages, you may need to install additional dependencies for the product to run properly.

To achieve similar rendering to Windows, especially when converted pages use fonts commonly found on Windows, it is recommended to install the Microsoft Core Fonts package on distributions that support it, such as Ubuntu and Debian.

The software is fully compatible with Azure App Service, Azure Functions and Docker containers on Linux. Separate documentation covers deployment to these platforms.

HiQPdf Chromium HTML to PDF Converter for Linux requires installing several system packages and optionally the Microsoft Core Fonts.

Install Dependency Packages

Required system packages vary slightly by distribution. Below are examples for the most common ones.

On Ubuntu 20.04, Ubuntu 22.04 or Debian 12, run:

sudo apt update && sudo apt install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libasound2

On Ubuntu 24.04 and Ubuntu 25.04, some packages have been replaced by their 64-bit equivalents:

sudo apt update && sudo apt install -y libnss3 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 libgbm1 libxkbcommon0 libpango-1.0-0 libcairo2 libasound2t64

On RedHat 9.5 or Amazon Linux 2023, run:

sudo dnf install -y nss atk at-spi2-atk cups-libs mesa-libgbm libxkbcommon pango cairo alsa-lib

Install Microsoft Core Fonts (Optional)

If your HTML pages use fonts commonly used on Windows, installing Microsoft Core Fonts is recommended for consistent rendering.

This package is officially supported on some distributions, such as Ubuntu and Debian. On other systems, it might not be available or may require manual installation.

If the ttf-mscorefonts-installer package is available (e.g., on Ubuntu virtual machines from Azure), run:

sudo apt update && sudo apt install ttf-mscorefonts-installer && sudo apt install fontconfig && sudo fc-cache -f -v

To automatically accept the license agreement and install the package, use:

echo 'ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true' | sudo debconf-set-selections && sudo apt update && sudo apt install -y ttf-mscorefonts-installer fontconfig && sudo fc-cache -f -v

If the ttf-mscorefonts-installer package is not available in your distribution, download and install it manually:

wget -O /tmp/ttf-mscorefonts-installer_3.8_all.deb http://ftp.de.debian.org/debian/pool/contrib/m/msttcorefonts/ttf-mscorefonts-installer_3.8_all.deb && sudo apt install -y /tmp/ttf-mscorefonts-installer_3.8_all.deb fontconfig && sudo fc-cache -f -v

And to accept the license automatically when installing manually:

wget -O /tmp/ttf-mscorefonts-installer_3.8_all.deb http://ftp.de.debian.org/debian/pool/contrib/m/msttcorefonts/ttf-mscorefonts-installer_3.8_all.deb && echo 'ttf-mscorefonts-installer msttcorefonts/accepted-mscorefonts-eula select true' | sudo debconf-set-selections && sudo apt install -y /tmp/ttf-mscorefonts-installer_3.8_all.deb fontconfig && sudo fc-cache -f -v

Before running the converter on Linux, ensure that the runtimes/linux-x64/native/hiqpdf_loadhtml file has execution permissions.

This file is automatically copied to your application's output directory after the NuGet package is installed and the project is built.

To grant execution permissions to hiqpdf_loadhtml, run the following command in the output directory:

chmod +x runtimes/linux-x64/native/hiqpdf_loadhtml

After configuring your Linux environment, you can start using the HiQPdf Chromium for .NET library in your applications.

Create a new .NET project in Visual Studio and use the NuGet Package Manager to install the HiQPdf.Chromium.Linux package.

After installing the NuGet package, add the following using statement at the top of your C# file to include the HiQPdf.Chromium namespace and make the library API available:

// add this using statement at the top of your C# file
using HiQPdf.Chromium;

You are now ready to convert web pages and HTML content to PDF or images using HiQPdf Chromium for .NET on Linux.

With the code below, you can convert an HTML string to a PDF document in a memory buffer and then save the data from the buffer to a file.

// Create the HTML to PDF converter object
HtmlToPdf converter = new HtmlToPdf();

// Convert the HTML code to memory
byte[] htmlToPdfData = converter.ConvertHtmlToMemory("<b>Hello World</b> from HiQPdf!", null);

// Save the PDF data to a file
System.IO.File.WriteAllBytes("html_to_memory.pdf", htmlToPdfData);

With the code below, you can convert a URL to a PDF document in a memory buffer and then save the data from the buffer to a file. The URL can also be a local file path prefixed with the file:// URI scheme.

// Create the HTML to PDF converter object
HtmlToPdf converter = new HtmlToPdf();

// Convert the HTML page from URL to memory
string urlToConvert = "http://www.hiqpdf.com";
byte[] urlToPdfData = converter.ConvertUrlToMemory(urlToConvert);

// Save the PDF data to a file
System.IO.File.WriteAllBytes("url_to_memory.pdf", urlToPdfData);

With the code below, you can convert an HTML string to a PDF document in a memory buffer in your ASP.NET Core applications, and then send it to the browser for download.

// Create the HTML to PDF converter object
HtmlToPdf converter = new HtmlToPdf();

// Convert the HTML code to memory
byte[] htmlToPdfData = converter.ConvertHtmlToMemory("<b>Hello World</b> from HiQPdf!", null);

FileResult fileResult = new FileContentResult(htmlToPdfData, "application/pdf");
fileResult.FileDownloadName = "html_to_pdf.pdf";
return fileResult;

With the code below, you can convert a URL to a PDF document in a memory buffer in your ASP.NET Core applications, and then send it to the browser for download. The URL can also be a local file path prefixed with the file:// URI scheme.

// Create the HTML to PDF converter object
HtmlToPdf converter = new HtmlToPdf();

// Convert the HTML code to memory
string urlToConvert = "http://www.hiqpdf.com";
byte[] urlToPdfData = converter.ConvertUrlToMemory(urlToConvert);

FileResult fileResult = new FileContentResult(urlToPdfData, "application/pdf");
fileResult.FileDownloadName = "url_to_pdf.pdf";
return fileResult;

At this point, everything should be configured and you can now run your application. Alternatively, you can follow the same instructions in this document to build and publish the ASP.NET demo application on Linux.

Reference

Other Resources