Usage Instructions for HiQPdf Chromium on Linux

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

The HTML to PDF converter uses Chromium as rendering engine which can render all the modern HTML, CSS and JavaScript in conformance with the latest standards and technologies.

HiQPdf Chromium HTML to PDF Converter for .NET can run natively on Linux 64-bit operating systems.

The .NET library is built for .NET Standard 2.0 which makes compatible with a wide range of .NET Core and .NET Framework versions starting with .NET Core 2.0 and going upwards to the latest versions available.

To be able to run the product on a Linux machine, it may be necessary to install additional packages, depending on the Linux distribution used and what is already installed.

The converter also requires an X11 Display Server to be installed. If such a server has already been installed as part of a desktop environment, then a separate installation is not necessary.

Additionally, for an experience as similar as possible between Linux and Windows, especially if the pages you are converting use fonts generally available on Windows, it is also recommended to install the Microsoft Core Fonts package for Linux.

The software is also fully compatible with Azure App Service and Azure Functions on Linux and the installation instructions for these platforms can be found in a separate documentation section.

The converter depends on various packages and it also requires an X11 display server to be installed and running.

If a desktop environment, such as Xfce which is a lightweight desktop environment for Linux operating systems, was already installed on the Linux machine, then a separate installation of the dependencies below is not necessary.

If a desktop environment was not previously installed, then follow the steps below to install the dependency packages and a lightweight virtual X11 display server such as Xvfb (X virtual framebuffer).

Install Dependency Packages

Install the dependency packages on the Linux machine, for example on Ubtuntu 20.04, using the command below:

sudo apt-get update && sudo apt-get install -y --no-install-recommends libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 libnss3 libgbm1

On Ubtuntu 24.04 the 'libasound2' package has been replaced by 'libasound2t64' package and the 'libgconf-2-4' package is no longer necessary. The modified command reflecting these changes is:

sudo apt-get update && sudo apt-get install -y --no-install-recommends libasound2t64 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 libnss3 libgbm1

Install Xvfb Virtual Framebuffer

Install the Xvfb X virtual framebuffer on a Linux machine, for example on Ubtuntu 20.04, using the command below:

sudo apt-get update && sudo apt-get install -y xvfb x11-apps x11-xkb-utils libx11-6 libx11-xcb1

Start the server to run in background as display number 99 using the command below:

sudo Xvfb :99 -screen 0 1920x1280x24 -ac +extension GLX +render -noreset &

Execute the command below to set the DISPLAY environment variable in the current session and also add the command in ~/.bash_profile file to ensure the variable is set in the new sessions:

export DISPLAY=:99

If the HTML pages you are converting use fonts generally available on Windows, it is also recommended to install the Microsoft Core Fonts package for Linux.

If the ttf-mscorefonts-installer package is available in Linux distribution the use the commands below to install Microsoft Core Fonts package, for example on Ubtuntu 20.04 :

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

If the ttf-mscorefonts-installer package is not available in Linux distribution the use the commands below to download the Microsoft Core Fonts package and install it:

wget http://ftp.de.debian.org/debian/pool/contrib/m/msttcorefonts/ttf-mscorefonts-installer_3.8_all.deb && sudo apt-get install -y ./ttf-mscorefonts-installer_3.8_all.deb

After the Linux environment was configured you can start using the HiQPdf Chromium HTML to PDF Converter for .NET library in your own applications.

Create a new .NET project in Visual Studio and use the NuGet Package Manager from Visual Studio to add a reference to the HiQPdf.Chromium.Linux package from NuGet. Build your application.

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

This file should have been copied to your application's output directory after the NuGet package was installed and your application was built.

To give the execution permission to hiqpdf_loadhtml file run the command below in your application output directory:

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

After the NuGet package has been installed, at the top of your C# source file add the using HiQPdf.Chromium; statement to include the HiQPdf.Chromium namespace in your application code and to make the library API available to your application.

// Include the HiQPdf namespace at the top of your C# file
using HiQPdf;

You are now ready to use the library to convert web pages and HTML code to PDF or to Image using HiQPdf Chromium HTML to PDF Converter.

With the code below you can convert a HTML string to a PDF document in a memory buffer and then save the data from buffer into 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 an URL to a PDF document in a memory buffer and then save the data from buffer into a file. The URL can also be a local file path prefixed by 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 in your ASP.NET Core applications a HTML string to a PDF document in a memory buffer and then send it for download to browser.

// 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 in your ASP.NET Core applications an URL to a PDF document in a memory buffer and then send it for download to browser. The URL can also be a local file path prefixed by 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;

Everything should have been configured at this point and now you can run your application. Alternatively, you can follow the same instructions from this document to build and publish on Linux our demo application for ASP.NET.

Reference

Other Resources