DEV Community

IronSoftware
IronSoftware

Posted on

Unable to Load Shared Library libgdiplus in Docker .NET (Issue Fixed)

#dotnet #csharp

Deploying .NET applications that use Aspose.PDF, Aspose.Slides, or other System.Drawing-dependent libraries to Docker containers on Linux results in a DllNotFoundException for libgdiplus. The application runs correctly in the Windows development environment but fails immediately when deployed to a Linux container. This article examines why this error occurs, the available workarounds, and an alternative approach that avoids the libgdiplus dependency entirely.

The Problem

When a .NET application using Aspose.PDF or similar libraries is deployed to a Docker container running on Linux, the first operation that touches graphics functionality throws an exception. The root cause is that these libraries depend on System.Drawing.Common, which requires GDI+ functionality. On Windows, GDI+ is built into the operating system. On Linux, System.Drawing.Common attempts to load libgdiplus, a third-party library that must be explicitly installed.

The Docker base images from Microsoft (mcr.microsoft.com/dotnet/aspnet, mcr.microsoft.com/dotnet/runtime) do not include libgdiplus because Microsoft deprecated System.Drawing.Common for non-Windows platforms starting with .NET 6. This creates a deployment gap: the application compiles successfully, the Docker image builds without errors, but the container crashes at runtime when the first graphics operation executes.

This issue affects any .NET library that depends on System.Drawing.Common, including:

  • Aspose.PDF for .NET
  • Aspose.Slides for .NET
  • Aspose.Cells for .NET (for chart/image operations)
  • Legacy applications using System.Drawing directly

Error Messages and Symptoms

The primary error message is:

System.DllNotFoundException: Unable to load shared library 'libgdiplus' or one of its dependencies.
In order to help diagnose loading problems, consider setting the LD_DEBUG environment variable: liblibgdiplus: cannot open shared object file: No such file or directory
Enter fullscreen mode Exit fullscreen mode

This exception is typically wrapped in a TypeInitializationException:

System.TypeInitializationException: The type initializer for 'Gdip' threw an exception.
 ---> System.DllNotFoundException: Unable to load shared library 'libgdiplus' or one of its dependencies.
   at System.Drawing.SafeNativeMethods.Gdip.GdiplusStartup(IntPtr& token, StartupInput& input, IntPtr& output)
   at System.Drawing.SafeNativeMethods.Gdip..cctor()
Enter fullscreen mode Exit fullscreen mode

For Aspose.Slides specifically, the error may appear as:

Aspose.Slides.PptxReadException: The type initializer for 'Gdip' threw an exception.
 ---> System.TypeInitializationException: The type initializer for 'Gdip' threw an exception.
 ---> System.DllNotFoundException: Unable to load shared library 'libgdiplus'
Enter fullscreen mode Exit fullscreen mode

Symptoms include:

  • Application works on Windows development machine, fails in Docker container
  • Docker image builds successfully, container crashes at runtime
  • Error occurs on first graphics operation (PDF generation, image processing, slide rendering)
  • CI/CD pipelines pass build stage but fail deployment tests
  • Kubernetes pods enter CrashLoopBackOff state

Who Is Affected

This issue impacts any .NET application deploying to Linux containers with System.Drawing.Common dependencies:

Operating Systems: Any Linux distribution in Docker containers, including Debian, Ubuntu, Alpine, and distroless images. The specific distribution matters for the workaround installation commands.

Framework Versions: .NET Core 2.1+, .NET 5, .NET 6, .NET 7, .NET 8, and .NET 9. The issue exists in all versions but workarounds differ. Starting with .NET 6, Microsoft requires an explicit configuration flag to enable System.Drawing.Common on non-Windows platforms.

Docker Base Images: All official Microsoft .NET images, including:

  • mcr.microsoft.com/dotnet/aspnet
  • mcr.microsoft.com/dotnet/runtime
  • mcr.microsoft.com/dotnet/sdk

Affected Libraries: Aspose.PDF, Aspose.Slides, Aspose.Cells, Aspose.Words (for certain operations), and any library depending on System.Drawing.Common.

Deployment Environments: Docker, Kubernetes, AWS ECS, Azure Container Apps, Google Cloud Run, and any containerized infrastructure running Linux.

Evidence from the Developer Community

The Stack Overflow question documenting this issue has accumulated over 57,000 views, indicating widespread impact across the .NET developer community.

Timeline

Date Event Source
2019-11-28 Initial Stack Overflow question posted Stack Overflow
2019-12-01 First answer with libgdiplus installation workaround Stack Overflow
2021-11-01 .NET 6 released, System.Drawing.Common deprecated on non-Windows Microsoft
2022-01-01 Reports increase as developers migrate to .NET 6 Stack Overflow
2024-05-03 Question continues receiving activity, 57K+ views Stack Overflow

Community Reports

"The application is normally working with development environment when I create a docker file for deployment it getting failed with libgdiplus issue."
— Developer, Stack Overflow, November 2019

The error messages from the original report:

PptxReadException: The type initializer for 'Gdip' threw an exception.
TypeInitializationException: The type initializer for 'Gdip' threw an exception.
DllNotFoundException: Unable to load shared library 'libgdiplus' or one of its dependencies
Enter fullscreen mode Exit fullscreen mode

This pattern appears repeatedly across Stack Overflow, GitHub issues, and Aspose forums. The common thread is: works on Windows, fails on Linux Docker containers.

Root Cause Analysis

The root cause is an architectural dependency chain:

  1. Aspose libraries use System.Drawing.Common for graphics operations
  2. System.Drawing.Common requires GDI+ for rendering
  3. GDI+ is a Windows-only technology built into the Windows OS
  4. On Linux, System.Drawing.Common requires libgdiplus as a GDI+ compatibility layer
  5. Docker images do not include libgdiplus by default
  6. Microsoft deprecated this approach starting with .NET 6

The libgdiplus library is a Mono project that reimplements the GDI+ API for non-Windows platforms. However, it has several problems:

  • Unmaintained: The project receives minimal updates
  • Memory leaks: Known memory management issues affect long-running processes
  • Inconsistent rendering: Output may differ from Windows GDI+
  • Deprecated by Microsoft: Officially recommended against for .NET 6+

Microsoft's documentation explicitly states:

"System.Drawing.Common will be supported only on Windows. Using System.Drawing.Common on non-Windows platforms will throw a PlatformNotSupportedException at run time."

Despite this deprecation, libraries like Aspose.PDF continue to depend on System.Drawing.Common, creating a conflict between library requirements and platform best practices.

Attempted Workarounds

Workaround 1: Install libgdiplus in Dockerfile

Approach: Add libgdiplus installation to your Dockerfile.

For Debian/Ubuntu-based images:

FROM mcr.microsoft.com/dotnet/aspnet:8.0

# Install libgdiplus and dependencies
RUN apt-get update && apt-get install -y \
    libgdiplus \
    libc6-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "YourApp.dll"]
Enter fullscreen mode Exit fullscreen mode

For Alpine-based images:

FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine

# Alpine uses a different package
RUN apk add --no-cache libgdiplus

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "YourApp.dll"]
Enter fullscreen mode Exit fullscreen mode

Limitations:

  • Increases Docker image size
  • libgdiplus has known memory leaks
  • Rendering may differ from Windows
  • Microsoft recommends against this approach for .NET 6+
  • Still requires runtime configuration switch for .NET 6+

Workaround 2: Enable System.Drawing.Common on Linux (.NET 6+)

Approach: For .NET 6 and later, add a runtime configuration switch.

Create or update runtimeconfig.template.json:

{
  "configProperties": {
    "System.Drawing.EnableUnixSupport": true
  }
}
Enter fullscreen mode Exit fullscreen mode

Or set via environment variable in Docker:

ENV DOTNET_SYSTEM_DRAWING_ENABLEUNIXSUPPORT=1
Enter fullscreen mode Exit fullscreen mode

Limitations:

  • Only suppresses the PlatformNotSupportedException
  • Still requires libgdiplus to be installed
  • Uses deprecated, buggy library
  • Not a supported configuration by Microsoft

Workaround 3: Use Windows Containers

Approach: Deploy to Windows containers instead of Linux.

FROM mcr.microsoft.com/dotnet/aspnet:8.0-nanoserver-ltsc2022

WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "YourApp.dll"]
Enter fullscreen mode Exit fullscreen mode

Limitations:

  • Windows containers are larger (several GB vs hundreds of MB)
  • Fewer hosting options in cloud environments
  • Higher infrastructure costs
  • Many Kubernetes clusters are Linux-only
  • Loses benefits of Linux container ecosystem

Workaround 4: Use Aspose's Drawing Package

Approach: Switch to Aspose.PDF.Drawing or similar packages marketed as System.Drawing-independent.

Limitations:

  • These packages may still have System.Drawing.Common dependencies internally
  • Feature parity issues with main packages
  • Evaluation watermarks appear in some scenarios
  • May introduce different bugs or limitations

A Different Approach: IronPDF

IronPDF uses a fundamentally different architecture that eliminates the libgdiplus dependency. Instead of relying on System.Drawing.Common, IronPDF embeds a Chromium rendering engine that provides native cross-platform support.

Why IronPDF Works in Docker Without libgdiplus

The architectural differences eliminate the dependency chain that causes the libgdiplus error:

  1. No System.Drawing.Common dependency: IronPDF does not use System.Drawing.Common for rendering
  2. Embedded Chromium: All rendering uses Chromium's graphics pipeline, which is native to Linux
  3. Self-contained binaries: Linux x64 and ARM64 binaries are included in the NuGet package
  4. Docker-ready by design: Official documentation and tested Dockerfiles available

Code Example 

using IronPdf;
using System;

/// <summary>
/// Demonstrates HTML-to-PDF conversion in Docker without libgdiplus dependency.
/// This code works identically on Windows and Linux containers.
/// </summary>
public class DockerPdfGenerator
{
    public void GeneratePdfInContainer()
    {
        // Optional: Configure for Linux/Docker environment
        // IronPDF auto-detects the platform and uses appropriate binaries
        Installation.LinuxAndDockerDependenciesAutoConfig = true;

        // Create the renderer - uses Chromium, not System.Drawing
        var renderer = new ChromePdfRenderer();

        // Configure rendering options
        renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;
        renderer.RenderingOptions.MarginTop = 25;
        renderer.RenderingOptions.MarginBottom = 25;

        // HTML content with images and CSS - all rendered by Chromium
        string html = @"
            <html>
            <head>
                <style>
                    body { font-family: 'Segoe UI', Arial, sans-serif; }
                    .header { background: #2c3e50; color: white; padding: 20px; }
                    .content { padding: 30px; }
                    img { max-width: 100%; }
                </style>
            </head>
            <body>
                <div class='header'>
                    <h1>Invoice #12345</h1>
                </div>
                <div class='content'>
                    <p>Generated in Docker container without libgdiplus.</p>
                    <img src='https://via.placeholder.com/400x200' alt='Chart' />
                </div>
            </body>
            </html>";

        // Render HTML to PDF - no libgdiplus required
        using (var pdf = renderer.RenderHtmlAsPdf(html))
        {
            // Save to file
            pdf.SaveAs("/app/output/invoice.pdf");

            // Or return as byte array for web response
            byte[] pdfBytes = pdf.BinaryData;
            Console.WriteLine($"Generated PDF: {pdfBytes.Length} bytes");
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

Dockerfile for IronPDF:

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["YourApp.csproj", "./"]
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /app/publish

FROM mcr.microsoft.com/dotnet/aspnet:8.0-bookworm-slim
WORKDIR /app

# IronPDF dependencies - NO libgdiplus needed
RUN apt-get update && apt-get install -y \
    libc6 \
    libgcc-s1 \
    libgssapi-krb5-2 \
    libicu72 \
    libssl3 \
    libstdc++6 \
    zlib1g \
    && rm -rf /var/lib/apt/lists/*

COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "YourApp.dll"]
Enter fullscreen mode Exit fullscreen mode

Key points about this code:

  • No libgdiplus installation in Dockerfile
  • No System.Drawing.EnableUnixSupport configuration needed
  • Same code runs on Windows, Linux, and macOS
  • Chromium handles all graphics operations natively
  • Images and CSS rendering work without GDI+ compatibility layer

API Reference

For more details on Docker deployment:

Migration Considerations

Licensing

IronPDF is commercial software with per-developer licensing. A free trial is available for evaluation. Teams should test their specific use cases before committing to migration.

API Differences

Migration from Aspose.PDF involves API changes:

Aspose.PDF IronPDF
Document class PdfDocument class
HtmlLoadOptions ChromePdfRenderer.RenderHtmlAsPdf()
Aspose.Pdf.Generator namespace ChromePdfRenderer

The HTML-to-PDF workflow simplifies significantly:

// Aspose.PDF approach
var doc = new Document();
var page = doc.Pages.Add();
HtmlFragment htmlFragment = new HtmlFragment(htmlContent);
page.Paragraphs.Add(htmlFragment);
doc.Save("output.pdf");

// IronPDF approach
var pdf = new ChromePdfRenderer().RenderHtmlAsPdf(htmlContent);
pdf.SaveAs("output.pdf");
Enter fullscreen mode Exit fullscreen mode

What You Gain

  • Deployment to Docker without libgdiplus installation
  • No deprecated System.Drawing.Common dependency
  • Consistent rendering between Windows and Linux
  • Smaller Docker images (no graphics library installation)
  • Works on Kubernetes, AWS Lambda, Azure Functions without modification

What to Consider

  • Commercial licensing cost
  • Chromium binaries increase NuGet package size (~200MB)
  • Different rendering engine may produce slight visual differences
  • API migration effort for existing codebases

Conclusion

The "Unable to load shared library libgdiplus" error in Docker stems from Aspose and similar libraries depending on System.Drawing.Common, which requires a GDI+ compatibility layer on Linux. While installing libgdiplus provides a workaround, it uses a deprecated, unmaintained library with known memory issues. For containerized deployments, using a PDF library that does not depend on System.Drawing.Common eliminates this class of deployment failures entirely.

Jacob Mellor has 25+ years of experience building developer tools, including IronPDF.

References

  1. Unable to load shared library 'libgdiplus' - Docker .NET application with Aspose API{:rel="nofollow"} - Original Stack Overflow question with 57K+ views
  2. System.Drawing.Common only supported on Windows - Microsoft Breaking Change{:rel="nofollow"} - Official Microsoft documentation on the deprecation
  3. libgdiplus GitHub Repository{:rel="nofollow"} - Mono project GDI+ compatibility library

For IronPDF documentation and tutorials, visit ironpdf.com.

Top comments (0)