IronPDF Linux Compatibility & Setup Guide
IronPDF supports Linux for .NET 8, 7, 6, 5 and .NET Core 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 IronPDF on 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 such as Azure Web Apps, Azure Functions, AWS EC2, AWS Lambda, Azure Devops Docker 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,
Hardware Specification
IronPDF uses Chromium to render HTML to PDF. The Chromium engine renders PDFs with pixel-perfect to Chrome's print feature. The hardware specifications are primarily for running the Chromium engine, which takes most of the computing power.
- Minimum : 1 Cores & 1.75 GB of RAM
- Recommended : 2 Cores & 8 GB of RAM or above
Officially Supported Linux Distros
We officially support and recommend the latest 64 bit Linux OS's below for "zero configuration" setup of IronPDF.
- Ubuntu 22
- Ubuntu 20
- Ubuntu 18
- Ubuntu 16
- Debian 11 [Currently the Microsoft Azure Default Linux Distro]
- Debian 10
- CentOS 8
- Fedora Linux 33
- Amazon AWS Linux 2 Read the AWS Lambda Setup Guide for IronPdf
Please Read "Other Linux Distros" below for advice on installing IronPdf on a version of Linux which is not officially supported.
We recommend using Microsoft's Official Docker Images. Other Linux distros are supported in part, but may require manual configuration using apt-get. See "Common Dependency Patterns for Linux" at the end of this document.
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 take longer than usual.
IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = true;IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = true;IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = TrueLinux Optimized NuGet Packages
Install-Package IronPdf.Linux
There are NuGet Packages available for Linux optimized IronPDF deployments documented in our IronPDF advanced NuGet installation guide.
You can use this Linux optimized package and even develop on a Windows or macOS machine.
Alternatively, you can directly download the DLL for Linux.
Docker + Linux Setup
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 it is used heavily in the Azure infrastructure we use for continuous testing and deployment. This platform also has official Microsoft .NET 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, 5, 6 (LTS), 7 and 8 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:
- 64 bit Ubuntu 20.04 Docker Image for .NET Runtime 3.1 ('3.1-focal')
- 64 bit Ubuntu 20.04 Docker Image for .NET Runtime 5.0 ('5.0-focal')
Manual Ubuntu 20 Setup If you wish to manually install or your app can not be run with sudo admin privileges.
Set IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = false;
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 libxshmfence1
apt install -y libgdiplus
apt install -y libva-dev
chmod 755 IronCefSubprocess
# (IronCefSubprocess is normally found at bin/runtimes/linux-x64/)- 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
runtimessubdirectory ofbin. - You may need
sudoprivileges.
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:
- 64 bit Ubuntu 18.04 Docker Image for .NET Runtime 3.1 ('3.1-bionic')
- Although there is no official docker image for .NET 5 on Ubuntu 18, compatibility is very high.
Manual Ubuntu 18 Setup If you wish to manually install or your app can not be run with sudo admin privileges.
Set IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = false;
apt update
apt install -y libc6
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 libxshmfence-dev
chmod 755 IronCefSubprocess
# (IronCefSubprocess is normally found at bin/runtimes/linux-x64/)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.
Manual Ubuntu 16 Setup If you wish to manually install or your app can not be run with sudo admin privileges.
Set IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = false;
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 libxshmfence-dev
chmod 755 IronCefSubprocess
# (IronCefSubprocess is normally found at bin/runtimes/linux-x64/)Debian Compatibility
Debian is our second most tested Linux operating system. This platform also has official Microsoft.NET support and Official Docker Images.
Debian 11
Debian 11 is the default Linux distribution used by Microsoft when adding Docker support to a .NET project in Visual Studio.
We support Debian 11 out of the box with zero configuration.
- Support Chrome and WebKit based HTML to PDF rendering Engines
- Officially support .NET Core 3.1, 5, 6 (LTS), 7 and 8 runtimes
- Unofficially we support many other .NET Core runtimes on Debian 11
- We run over 997 Unit tests on this platform before every release
Official Microsoft Docker Images:
- 64 bit Debian 11 Docker Image for .NET Runtime 3.1
- 64 bit Debian 11 Docker Image for .NET Runtime 5.0
Manual Debian 11 Setup If you wish to manually install or your app can not be run with sudo admin privileges.
Set IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = false;
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 libxkbcommon-x11-0
apt install -y libxrender1
apt install -y libfontconfig1
apt install -y libxshmfence1
chmod 755 IronCefSubprocess
# (IronCefSubprocess is normally found at bin/runtimes/linux-x64/)Debian 10
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, 5, 6 (LTS), 7 and 8 runtimes
- Unofficially we support many other .NET Core runtimes on Debian 10
- We run over 997 Unit tests on this platform before every release
Official Microsoft Docker Images:
- 64 bit Debian 10 Docker Image for .NET Runtime 3.1
- 64 bit Debian 10 Docker Image for .NET Runtime 5.0
Manual Debian 10 Setup If you wish to manually install or your app can not be run with sudo admin privileges.
Set IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = false;
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 libxshmfence1
chmod 755 IronCefSubprocess
# (IronCefSubprocess is normally found at bin/runtimes/linux-x64/)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 "Common Dependency Patterns for Linux" 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 CentOS 8 out of the box with zero configuration.
- Support Chrome and WebKit based HTML to PDF rendering Engines
- Officially support .NET Core 3.1, 5, 6 (LTS), 7 and 8 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.
Manual CentOS 8 Setup If you wish to manually install or your app can not be run with sudo admin privileges.
Set IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = false;
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 libXdamage
dnf -y install libxshmfence
chmod 755 IronCefSubprocess
# (IronCefSubprocess is normally found at bin/runtimes/linux-x64/)CentOS 7 and Lower
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 "Common Dependency Patterns for Linux" 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
We reccomend that you read our IronPDF AWS Lambda guide which contains a working Docker file for IronPdf on AWS Lambda.
Amazon Linux 2 Manual Setup
If you wish to manually install or your app can not be run with sudo admin privileges. Set IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = false;
yum update -y
yum install -y pango.x86_64
yum install -y libXcomposite.x86_64
yum install -y libXcursor.x86_64
yum install -y libXdamage.x86_64
yum install -y libXext.x86_64
yum install -y libXi.x86_64
yum install -y libXtst.x86_64
yum install -y cups-libs.x86_64
yum install -y libXScrnSaver.x86_64
yum install -y libXrandr.x86_64
yum install -y GConf2.x86_64
yum install -y alsa-lib.x86_64
yum install -y atk.x86_64
yum install -y gtk3.x86_64
yum install -y ipa-gothic-fonts
yum install -y xorg-x11-fonts-100dpi
yum install -y xorg-x11-fonts-75dpi
yum install -y xorg-x11-utils
yum install -y xorg-x11-fonts-cyrillic
yum install -y xorg-x11-fonts-Type1
yum install -y xorg-x11-fonts-misc
yum install -y glibc-devel.x86_64
yum install -y at-spi2-atk.x86_64
yum install -y mesa-libgbm.x86_64
yum install -y libxkbcommon
chmod 755 IronCefSubprocess
# (IronCefSubprocess is normally found at bin/runtimes/linux-x64/)Please also read our documentation on our official support IronPdf for AWS Lambda that includes installation and logging on the Amazon cloud platform.
Fedora Linux Compatibility
Fedora Linux is supported.
We support Fedora Linux 33 out of the box with zero configuration.
- Support Chrome and WebKit based HTML to PDF rendering Engines
- Officially support .NET Core 3.1, 5, 6 (LTS), 7 and 8 runtimes
- We run comprehensive smoke tests on this platform before every release
Manual Fedora Linux Setup If you wish to manually install or your app can not be run with sudo admin privileges. This may also help with older or newer builds of Fedora Linux.
Set IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = false;
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 libXdamage
dnf -y install libxshmfence
chmod 755 IronCefSubprocess
# (IronCefSubprocess is normally found at bin/runtimes/linux-x64/)Alpine Linux Compatibility
Running IronPDF on 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 2023, Alpine still uses outdated "musl" C language libraries that do not allow chromium developers to fully support this OS yet.
Using Alpine Docker with IronPdfEngine in .NET 6
IronPdf provides a container image containing all IronPdf functionalities. This enables projects running on Alpine to access IronPdf functionalities by connecting to IronPdfEngine container.
Step 1: Pull and Run IronPdf Engine Docker Image
Execute the following commands in your terminal to pull and run the IronPdf Engine Docker image:
docker pull ironsoftwareofficial/ironpdfenginedocker run -d -p 33350:33350 ironsoftwareofficial/ironpdfengineStep 2: Set Up Console App
Create a new console application targeting .NET 6. Install the IronPdf.Slim NuGet package using the NuGet Package Manager.
Other Linux Distros
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
runtimessubdirectory ofbin. - You may need
sudoprivileges.
If you are uncertain how to proceed with an unlisted Linux OS; investigate the dependancies for Chromium browser on that OS.
If you want to vote for offical support for a different linux distro, please contact support@ironsoftware.com with your request.
Common Dependency Patterns for Linux Please also study the dependency packages for other linux OS's above.
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 libxshmfence1
chmod 755 IronCefSubprocess
# (IronCefSubprocess is normally found at bin/runtimes/linux-x64/)IronCefSubprocess
IronCefSubprocess is a binary file within your application's bin folder. It needs to be executable by the .NET process.
E.g. (path may vary)
chmod 755 bin/runtimes/linux-64/IronCefSubprocessdotnet single-file publishing in Linux
If you choose to export your project as single-file publishing on Linux, this is how to do it.
dotnet publish -r linux-x64 /property:PublishProfile=FolderProfile /blTemp File Paths
Developers may need to specify a writable directory where temporary files can be created for some use cases.
A common, safe value for this path is /tmp/ in Linux, but ultimately it must be a path where the user can read and write files.
//set IronPDF Temp Path
string tmpPath = @"/tmp/";
IronPdf.Logging.Logger.LogFilePath = tmpPath;
Environment.SetEnvironmentVariable("TEMP", tmpPath, EnvironmentVariableTarget.Process);
Environment.SetEnvironmentVariable("TMP", tmpPath, EnvironmentVariableTarget.Process);
IronPdf.Installation.TempFolderPath = tmpPath;
IronPdf.Installation.CustomDeploymentDirectory = tmpPath;//set IronPDF Temp Path
string tmpPath = @"/tmp/";
IronPdf.Logging.Logger.LogFilePath = tmpPath;
Environment.SetEnvironmentVariable("TEMP", tmpPath, EnvironmentVariableTarget.Process);
Environment.SetEnvironmentVariable("TMP", tmpPath, EnvironmentVariableTarget.Process);
IronPdf.Installation.TempFolderPath = tmpPath;
IronPdf.Installation.CustomDeploymentDirectory = tmpPath;'set IronPDF Temp Path
Dim tmpPath As String = "/tmp/"
IronPdf.Logging.Logger.LogFilePath = tmpPath
Environment.SetEnvironmentVariable("TEMP", tmpPath, EnvironmentVariableTarget.Process)
Environment.SetEnvironmentVariable("TMP", tmpPath, EnvironmentVariableTarget.Process)
IronPdf.Installation.TempFolderPath = tmpPath
IronPdf.Installation.CustomDeploymentDirectory = tmpPath
