Adding IronPDF to an Existing Docker Container

ByChaknith Bin

May 31, 2025

Updated June 22, 2025

IronPDF for .NET Standard now fully supports Docker, including Azure Docker Containers for Linux and Windows.

Do you want to deploy IronPDF as a separate Docker container instead? Learn more about the IronPDF Engine tutorials guide.

Why use Docker on Azure?

Alongside excellent enterprise scalability, Docker Containers on Azure enjoy more permissions than regular WebApps.
This allows rendering of SVG fonts because system access to GDI+ graphics is enabled.

IronPDF and Linux Primer

If Docker with .NET is new to you, we recommend this excellent article on setting up Docker debugging and integration with Visual Studio projects.

We also highly recommend you read our IronPDF Linux Setup and Compatibility Guide

Recommended Linux Docker Distributions

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

Ubuntu 22
Ubuntu 20
Ubuntu 18
Debian 11
Debian 10 [Currently the Microsoft Azure Default Linux Distro]
CentOS 8
Amazon AWS Linux 2 Read the IronPDF AWS Lambda Setup Guide

We recommend using Microsoft's Official Docker Images for .NET. Other Linux distros are supported in part, but may require manual configuration using apt-get. See our "Linux Manual Setup" guide.

Working Docker files for Ubuntu and Debian are included in this document:

IronPDF Linux Docker Installation Essentials

Use Linux Optimised NuGet Packages

We recommend using the IronPdf.Linux NuGet Package instead of the regular IronPdf Package to save disk space and avoid assets being downloaded when you start your Docker instance. Don't worry, it still works when developing on Windows or macOS - it is just Linux optimized.

# Install the IronPdf.Linux package to optimize for Linux environments
Install-Package IronPdf.Linux

# Install the IronPdf.Linux package to optimize for Linux environments
Install-Package IronPdf.Linux

SHELL

Another solution is to simply add IronPdf.Native.Chrome.Linux on top of the regular IronPdf NuGet package.

# Install the IronPdf.Native.Chrome.Linux package for native Chrome support on Linux
Install-Package IronPdf.Native.Chrome.Linux

# Install the IronPdf.Native.Chrome.Linux package for native Chrome support on Linux
Install-Package IronPdf.Native.Chrome.Linux

SHELL

Avoid Automatic Dependency Installation

Many users report better results with Linux & Docker when LinuxAndDockerDependenciesAutoConfig is set to false. This is because the prerequisites are already installed by apt-get style package managers already in your Docker files.

// Disable automatic dependency installation for better control over prerequisites
IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = false;

// Disable automatic dependency installation for better control over prerequisites
IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = false;

' Disable automatic dependency installation for better control over prerequisites
IronPdf.Installation.LinuxAndDockerDependenciesAutoConfig = False

$vbLabelText $csharpLabel

Disable GPU Acceleration

Linux Docker containers often do not have access to a GPU. GPU acceleration is disabled by default. If you have enabled ChromeGpuModes.Enabled, we highly recommend you disable it for Docker deployments:

// Disable GPU acceleration as most Docker containers do not have GPU access
IronPdf.Installation.ChromeGpuMode = IronPdf.Engines.Chrome.ChromeGpuModes.Disabled;

// Disable GPU acceleration as most Docker containers do not have GPU access
IronPdf.Installation.ChromeGpuMode = IronPdf.Engines.Chrome.ChromeGpuModes.Disabled;

' Disable GPU acceleration as most Docker containers do not have GPU access
IronPdf.Installation.ChromeGpuMode = IronPdf.Engines.Chrome.ChromeGpuModes.Disabled

$vbLabelText $csharpLabel

"Ahead of Time" Initialization

Optionally, you may also wish to call the IronPdf.Installation.Initialize() method to manually start IronPDF. The very first time a Docker instance uses IronPDF, it may take some time to download prerequisites. We can avoid that scenario by calling this code when the instance is created:

// Call initialize to preemptively load required resources and avoid delay
IronPdf.Installation.Initialize();

// Call initialize to preemptively load required resources and avoid delay
IronPdf.Installation.Initialize();

' Call initialize to preemptively load required resources and avoid delay
IronPdf.Installation.Initialize()

$vbLabelText $csharpLabel

Ubuntu Linux DockerFiles

Ubuntu 22 with .NET 8

Ubuntu 22 with .NET 7

Ubuntu 20 with .NET 6

Ubuntu 20 with .NET 5

Ubuntu 20 with .NET 3.1 LTS

Ubuntu 18 with .NET 3.1 LTS

Debian Linux DockerFiles

Debian 12 with .NET 8

Debian 11 with .NET 7

Debian 11 with .NET 6

Debian 11 with .NET 5

Debian 11 with .NET 3.1 LTS

Debian 10 with .NET 5

Debian 10 with .NET 3.1 LTS

Alpine Linux DockerFiles

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 an 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:

# Pull the IronPdfEngine Docker image from Docker Hub
docker pull ironsoftwareofficial/ironpdfengine

# Run the IronPdfEngine Docker image, mapping to port 33350
docker run -d -p 33350:33350 ironsoftwareofficial/ironpdfengine

# Pull the IronPdfEngine Docker image from Docker Hub
docker pull ironsoftwareofficial/ironpdfengine

# Run the IronPdfEngine Docker image, mapping to port 33350
docker run -d -p 33350:33350 ironsoftwareofficial/ironpdfengine

SHELL

Step 2: Set Up Console App

Create a new console application targeting .NET 6. Install the IronPdf.Slim NuGet package using the NuGet Package Manager.

IronPDF Windows Docker Containers

Windows Docker Containers are becoming increasingly popular on Azure, as they give higher levels of performance and scalability, and give developers more permissions to configure instances.

IronPDF will actually perform more attractive text rendering within a Docker container (Windows or Linux) on Azure because of higher levels of access to graphics library and the virtual graphics card.

The article 'Visual Studio Container Tools for Docker' is a really great get-started guide.

This is an example Windows container Dockerfile for .NET Core 3.1

Windows Server 2019 .NET 6.0

Pre-configured Windows containers include all the necessary dependencies for running IronPdf.

Please note

That these containers are not intended for building .NET applications. Rather, the should be used for running them.

# Use the .NET SDK base image for building the application
FROM mcr.microsoft.com/dotnet/sdk:6.0-windowsservercore-ltsc2019 AS build

# Set the working directory
WORKDIR /src

# Copy the nuget configuration and project files
COPY ["nuget.config", "."]
COPY ["ConsoleApp/ConsoleApp.csproj", "ConsoleApp/"]

# Restore the necessary packages
RUN dotnet restore "ConsoleApp/ConsoleApp.csproj"

# Copy the entire solution and build it
COPY . .
WORKDIR "/src/ConsoleApp"
RUN dotnet build "ConsoleApp.csproj" -c Release -o /app/build

# Publish the application
FROM build AS publish
RUN dotnet publish "ConsoleApp.csproj" -c Release -o /app/publish /p:UseAppHost=false

# Use the official IronPDF Windows image to run the application
FROM ironsoftwareofficial/windows:2019-net60

# Set the working directory in the container for running the app
WORKDIR /app

# Copy the published app from the build stage
COPY --from=publish /app/publish .

# Define the entry point for running the application
ENTRYPOINT ["dotnet", "ConsoleApp.dll"]

Visit the IronSoftware's Docker repository on Docker Hub to explore additional pre-configured images for running IronPdf.

Frequently Asked Questions

What is a library for generating PDFs in C# applications and how does it work with Docker?

IronPDF is a library for generating PDFs in C# applications. It fully supports Docker, allowing you to run your PDF applications in containerized environments on Linux, Windows, and Azure.

Why use Docker containers on Azure for PDF generation?

Docker containers on Azure offer excellent enterprise scalability and more permissions than regular WebApps, which allows rendering of SVG fonts through system access to GDI+ graphics when using IronPDF.

Which Linux distributions are recommended for PDF generation with Docker setups?

For an easy configuration of IronPDF, we recommend using 64-bit versions of Ubuntu 22, Ubuntu 20, Ubuntu 18, Debian 11, Debian 10, CentOS 8, and Amazon AWS Linux 2.

How can I optimize PDF generation for Linux environments?

It is recommended to use the IronPdf.Linux NuGet Package or add IronPdf.Native.Chrome.Linux on top of the regular IronPdf package to save disk space and optimize for Linux environments.

What is the importance of disabling automatic dependency installation in Docker?

Disabling automatic dependency installation gives better control over prerequisites when using IronPDF, as they are often already installed using package managers like apt-get in your Docker files.

Should GPU acceleration be enabled in Docker containers for PDF generation?

No, GPU acceleration should be disabled as most Docker containers do not have access to a GPU. This is the default setting for IronPDF, but if enabled, it should be turned off for Docker deployments.

What is 'Ahead of Time' Initialization and why is it used?

'Ahead of Time' Initialization involves calling the IronPdf.Installation.Initialize() method to manually start IronPDF and preemptively load required resources to avoid delays during the first use of a Docker instance.

Is Alpine Linux supported for running PDF generation libraries?

Running IronPDF on Alpine Linux is not supported due to outdated 'musl' C language libraries that don't allow full Chromium support. However, IronPdf functionalities can be accessed by connecting to an IronPdfEngine container.

What are the benefits of using Windows Docker Containers for PDF generation?

Windows Docker Containers on Azure offer higher levels of performance and scalability, and provide more permissions to configure instances, enabling more attractive text rendering with IronPDF due to better access to graphics libraries and virtual graphics cards.

Where can I find pre-configured Docker images for PDF generation libraries?

Pre-configured Docker images for running IronPDF can be found on IronSoftware's Docker repository on Docker Hub, offering various setups for different environments and requirements.

Chaknith Bin

Chat with engineering team now

Software Engineer

Chaknith works on IronXL and IronBarcode. He has deep expertise in C# and .NET, helping improve the software and support customers. His insights from user interactions contribute to better products, documentation, and overall experience.