IronPDF Linux Compatibility & Setup Guide

IronPDF supports Linux for .NET Core and .Net 5 applications, as well as Docker, Azure, AWS, MacOS and (naturally) Windows.

We recommend using .NET Core 3.1 and any other runtimes marked as LTS by Microsoft because they have guaranteed long term support and are generally well tested on Linux.

No code changes are required to run on IronPDF Linux. Generally IronPDF works out of the box thanks to hundreds of hours of testing and configuration by our engineers.

Linux support is important because many cloud service suck as Azure Web Apps, Azure Functions, AWS EC2, AWS Lambda, Azure Devops Docker new rely heavily on Linux. At Iron Software we use these cloud tools regularly and understand that many of our Enterprise and SAAS customers do too,

Short Summary for Busy Developers

We recommend the latest 64 bit Linux OS's below for "zero configuration" setup of IronPDF.

  • Ubuntu 20
  • Ubuntu 18
  • Debian 10 [Currently the Microsoft Azure Default Linux Distro]
  • CentOS 8
  • Amazon AWS Linux 2 [ For Amazon Cloud Hosting ]

We recommend using Microsofts Official Docker Images . Other Linux distros are supported in part, but may require manual configuration using apt-get. See "Linux Manual Setup" at the end of this document.

We currently can not support Alpine Linux until it modernizes its use of MUSL C libraries in the kernel.

Linux Optimized Nuget Packages

PM > Install-Package IronPdf.Linux

There is a Nuget Packages available for Linux optimized IronPDF deployments documeted in our IronPDF advanced Nuget installation guide.

Docker Primer

Please read our extensive documentation on using IronPDF on Docker if you need help setting up a Docker image that will use IronPDF.

Ubuntu Compatibility

Ubuntu is our most tested Linux operating system. This is because is it is used heavily in the Azure infrastructure we use for continuous testing and deployment. This platform also has official Microsoft DotNet support and Official Docker Images.

Ubuntu 20

We support Ubuntu 20 out of the box with zero configuration.

  • Support Chrome and WebKit based HTML to PDF rendering Engines
  • Officially Support .NET Core 3.1 LTS and .NET 5 runtimes
  • Unofficially we support many other .Net Core runtimes on Ubuntu 20
  • We run over 997 Unit tests on this platform before every release

Official Microsoft Docker Images:

Ubuntu 18

We support Ubuntu 18 out of the box with zero configuration.

  • Support Chrome and WebKit based HTML to PDF rendering Engines
  • Official Support .NET Core 3.1 LTS and .NET 5 runtimes
  • Unofficially we support many other .Net Core runtimes on Ubuntu 18 and even 16
  • We run comprehensive smoke tests on this platform before every release

Official Microsoft Docker Images:

Ubuntu 16

We have only limited / unofficial support Ubuntu 16. Ubuntu 16 has not been rigorously tested with IronPdf.

.NET on Ubuntu 16 is officially supported by Microsoft and is reported to work with IronPdf by many users. Developers may have to install apt-get dependancies manually.

  • Chrome and WebKit normally work with manual config.
  • .NET Core 3.1 LTS and .NET 5 runtimes have Microsoft support for Ubuntu 16.
  • There are currently no official Microsoft Docker images for Ubuntu 16.

Debian Compatibility

Debian is our second most tested Linux operating system. This platform also has official Microsoft DotNet support and Official Docker Images.

Debian 10

Debian 10 is the default Linux distribution used by Microsoft when adding Docker support to a .NET project in Visual Studio.

We support Debian 10 out of the box with zero configuration.

  • Support Chrome and WebKit based HTML to PDF rendering Engines
  • Officially Support .NET Core 3.1 LTS and .NET 5 runtimes
  • Unofficially we supports many other .Net Core runtimes on Debian 10
  • We run over 997 Unit tests on this platform before every release

Official Microsoft Docker Images:

Debian 9 and Lower

Debian 9 is not been officially tested and will not work out-of-the box with IronPdf. However .NET on Debian 9 is officially supported by Microsoft and can work with IronPdf if set-up correctly (See "Linux Manual Setup" at the end of this document).

There are no official Docker images by Microsoft for .NET Core 3.1 or .NET 5.0 on Debian 9. We highly recommend migrating to Debian 10.

CentOS Compatibility

We actively like and support CentOS.

CentOs 8 Support

We support Debian 8 out of the box with zero configuration.

  • Support Chrome and WebKit based HTML to PDF rendering Engines
  • Officially Support .NET Core 3.1 LTS and .NET 5 runtimes
  • Unofficially we support many other .Net Core runtimes on CentOs
  • We run comprehensive smoke tests on this platform before every release

Sadly there are no official Docker images by Microsoft for .NET Core 3.1 or .NET 5.0 on CentOS 8.

CentOs 7 And Below

CentOS 7 has not been tested and will not work out-of-the box with IronPdf.

However, .NET on CentOS 7 is officially supported by Microsoft and would likely work with IronPdf if set-up correctly (please read "Linux Manual Setup" below).

There are no official Docker images by Microsoft for .NET Core 3.1 or .NET 5.0 on CentOS 7.

Amazon AWS Linux 2 Compatibility

We have working support for Amazon AWS Linux 2 which forms the basis of Amazon's cloud services such as EC2 and Lambda.

  • There are no official Docker images by Microsoft for .NET Core 3.1 or .NET 5.0 on Amazon AWS Linux 2.
  • We manually test for Amazon AWS Linux 2 compatibility as we develop IronPDF

Alpine Linux Compatibility

Alpine Linux is not supported. We wish we could but we can't.

Frankly we like Alpine and hope this project continues and grows.

As of 2021, Alpine still uses outdated "musl" C language libraries that do not allow chromium developers to fully support this OS yet.

Google's Chromium Embedded team and our engineers will support Alpine when it updates its native support for modern C and C++.

Linux Automatic Setup

The default setting LinuxAndDockerDependenciesAutoConfig true will automatically attempt to install all dependencies for IronPDF to run on Linux. The first html-to-pdf operation may be longer than usual packages that are installed.

IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = true;
IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = true;
IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = True
VB   C#

This works on all officially supported Docker images. and Linux Distros where the application has sudo level user privileges.

Linux Manual Setup

You can also manually install the IronPDF prerequisites for Linux using apt-get hfs and yum This allows you to use IronPDF on many unsupported linux distros.

Generally during installation for the first time IronPDF will throw exceptions to tell you of any necessary system dependancies.

  • IronCefSubprocess mentioned below is a binary within your application's bin folder. You may need to specify an exact path which may be in the runtimes subdirectory of bin.
  • You may need sudo privileges.

If you are uncertain how to proceed with an unlisted Linux OS; investigate the dependancies for Chromium browser on that OS.

Apt-Get Package Manager

The most common Package Manager

apt update
apt install -y libc6-dev
apt install -y libgtk2.0-0
apt install -y libnss3
apt install -y libatk-bridge2.0-0
apt install -y libx11-xcb1
apt install -y libxcb-dri3-0
apt install -y libdrm-common
apt install -y libgbm1
apt install -y libasound2
apt install -y libappindicator3-1
apt install -y libxrender1
apt install -y libfontconfig1
apt install -y xvfb  

chmod 755 IronCefSubprocess 
Xvfb -ac :99 -screen 0 1920x1080x24 -nolock &

DNF Package Manager

Seen in older CentOS

dnf -y update,
dnf -y install glibc-devel,
dnf -y install nss,
dnf -y install at-spi2-atk,
dnf -y install libXcomposite,
dnf -y install libXrandr,
dnf -y install mesa-libgbm,
dnf -y install alsa-lib,
dnf -y install pango,
dnf -y install cups-libs,
dnf -y install xorg-x11-server-Xvfb

chmod 755 IronCefSubprocess
Xvfb -ac :99 -screen 0 1920x1080x24 -nolock &

Yum Package Manager

Seen in Amazon AWS linux

yum update -y
yum install -y glibc-devel.x86_64
yum install -y at-spi2-atk.x86_64
yum install -y libXcomposite-devel.x86_64
yum install -y libXrandr.x86_64
yum install -y mesa-libgbm.x86_64
yum install -y alsa-lib.x86_64
yum install -y pango.x86_64
yum install -y cups-libs.x86_64
yum install -y xorg-x11-server-Xvfb.x86_64 

chmod 755 IronCefSubprocess
Xvfb -ac :99 -screen 0 1920x1080x24 -nolock &
Previous Tutorial
Next Tutorial