SelectPdf Linux Error: Unable to Load kernel32.dll (Issue Fixed)

Developers attempting to use SelectPdf on Linux environments encounter a runtime exception: Unable to load shared library 'kernel32.dll' or one of its dependencies. This error indicates a fundamental platform limitation rather than a configuration issue. SelectPdf is a Windows-only library with no Linux support.

The Problem

SelectPdf relies on Windows-specific native libraries, including kernel32.dll, which is a core Windows system component. When developers deploy applications using SelectPdf to Linux servers, Docker containers, or other non-Windows environments, the application fails immediately upon attempting any PDF operation.

This limitation affects developers who initially build and test on Windows development machines, only to discover the incompatibility when deploying to production Linux environments. The error occurs regardless of .NET version, framework configuration, or runtime settings because the underlying dependency simply does not exist on Linux.

Unlike some libraries where Linux compatibility issues stem from optional dependencies that can be worked around, SelectPdf's Windows-only architecture means there is no configuration change, package installation, or code modification that enables Linux operation.

Error Messages and Symptoms

System.DllNotFoundException: Unable to load shared library 'kernel32.dll' or one of its dependencies.
In order to help diagnose loading problems, consider setting the LD_DEBUG environment variable:
libkernel32.dll: cannot open shared object file: No such file or directory

The error surfaces immediately when SelectPdf attempts to initialize its rendering engine, preventing any HTML-to-PDF conversion from occurring.

Who Is Affected

This limitation impacts developers in several common scenarios:

• Linux server deployments (Ubuntu, Debian, CentOS, RHEL, Alpine)
• Docker containerized applications using Linux base images
• Azure App Service on Linux
• AWS Lambda and other serverless platforms
• CI/CD pipelines running on Linux build agents
• Kubernetes deployments with Linux nodes
• macOS development environments

The issue affects all .NET versions including .NET Core 3.1, .NET 5, .NET 6, .NET 7, and .NET 8. Since the limitation is architectural rather than version-specific, no framework update resolves it.

Evidence from the Developer Community

Developers have reported this issue across multiple channels, consistently receiving the same response: SelectPdf does not support Linux.

Timeline

Date	Event	Source
2021-02-10	First GitHub issue opened	GitHub
2021-02-10	Official response confirms Windows-only	GitHub
2025-01-20	No Linux support announced	-

Community Reports

"Unable to load shared library 'kernel32.dll' or one of its dependencies"
-- GitHub Issue #2, SelectPdf Repository, 2021

The GitHub issue repository for SelectPdf shows multiple developers encountering this same limitation when attempting Linux deployments. The maintainer response confirms SelectPdf's Windows-only architecture.

Additional developers on Stack Overflow and Reddit have reported discovering this limitation only after building applications with SelectPdf, leading to significant refactoring efforts when deployment requirements included Linux environments.

Root Cause Analysis

SelectPdf depends directly on Windows API calls through P/Invoke to kernel32.dll and potentially other Windows system libraries. This architectural decision means:

1. Native Dependency: The library makes system calls to Windows kernel functions that have no Linux equivalents
2. No Abstraction Layer: Unlike cross-platform libraries that use abstraction layers (like .NET's own cross-platform APIs), SelectPdf calls Windows APIs directly
3. Binary Incompatibility: The compiled native components are Windows PE (Portable Executable) format, not Linux ELF format

This is not a bug that can be fixed with a patch or configuration change. Supporting Linux would require a complete rewrite of SelectPdf's rendering engine architecture, which the maintainers have indicated is not planned.

Attempted Workarounds

Workaround 1: Wine Compatibility Layer

Approach: Some developers have attempted running SelectPdf through Wine on Linux.

Limitations:

• Unreliable rendering results
• Performance overhead
• Additional deployment complexity
• Not suitable for production environments
• Incompatible with containerized deployments

Workaround 2: Windows Container

Approach: Using Windows containers instead of Linux containers.

Limitations:

• Windows containers have significantly larger image sizes (gigabytes vs megabytes)
• Limited orchestration platform support
• Higher resource consumption
• Increased licensing costs
• Many cloud platforms prefer or require Linux containers

Workaround 3: Remote Windows Service

Approach: Running a separate Windows service/API that handles PDF generation.

Limitations:

• Added infrastructure complexity
• Network latency for each PDF operation
• Additional points of failure
• Higher operational costs
• Complicates deployment pipelines

None of these workarounds provide a production-ready solution for Linux deployments.

A Different Approach: IronPDF

For developers who need cross-platform PDF generation, IronPDF provides native support for Windows, Linux, macOS, and Docker environments. The library uses a self-contained Chromium-based rendering engine that ships with the package, eliminating external dependencies.

Why IronPDF Works on Linux

IronPDF's architecture differs fundamentally from SelectPdf:

1. Embedded Rendering Engine: IronPDF includes its own Chromium-based renderer, packaged as platform-specific native binaries for each supported OS
2. Platform Detection: The library automatically loads the correct native components based on the runtime environment
3. No System Dependencies: Linux deployments require minimal additional packages (standard libraries that most distributions include by default)
4. Docker-Native Support: IronPDF provides tested Docker configurations and base images

Code Example: HTML to PDF on Linux

using IronPdf;

// IronPDF works identically on Windows, Linux, and macOS
// No platform-specific code required

public class LinuxPdfGenerator
{
    public void GeneratePdfFromHtml()
    {
        // Configure renderer for Linux environment
        // Note: This configuration works on any platform
        var renderer = new ChromePdfRenderer();

        // Set rendering options
        renderer.RenderingOptions.MarginTop = 20;
        renderer.RenderingOptions.MarginBottom = 20;
        renderer.RenderingOptions.PaperSize = IronPdf.Rendering.PdfPaperSize.A4;

        // Convert HTML string to PDF
        string html = @"
            <html>
            <head>
                <style>
                    body { font-family: Arial, sans-serif; }
                    h1 { color: #333; }
                </style>
            </head>
            <body>
                <h1>Generated on Linux</h1>
                <p>This PDF was created using IronPDF running on a Linux server.</p>
            </body>
            </html>";

        var pdf = renderer.RenderHtmlAsPdf(html);

        // Save to file
        pdf.SaveAs("/app/output/document.pdf");
    }
}

Key points about this code:

• The code runs identically on Windows, Linux, and macOS
• No platform-specific configuration required
• IronPDF handles native library loading automatically
• Full CSS and JavaScript support via Chromium engine

Docker Deployment Example

# Dockerfile for IronPDF on Linux
FROM mcr.microsoft.com/dotnet/aspnet:8.0

# Install minimal dependencies for IronPDF
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"]

using IronPdf;

// Docker-specific configuration (optional, for optimization)
public class DockerPdfService
{
    public byte[] ConvertHtmlToPdf(string htmlContent)
    {
        // Enable Docker compatibility mode
        Installation.LinuxAndDockerDependenciesAutoConfig = true;

        var renderer = new ChromePdfRenderer();

        // Configure for containerized environment
        renderer.RenderingOptions.EnableJavaScript = true;
        renderer.RenderingOptions.RenderDelay = 500; // Wait for JS execution

        var pdf = renderer.RenderHtmlAsPdf(htmlContent);

        return pdf.BinaryData;
    }
}

Azure App Service on Linux

using IronPdf;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class PdfController : ControllerBase
{
    [HttpPost("generate")]
    public IActionResult GeneratePdf([FromBody] string htmlContent)
    {
        // Works on Azure App Service Linux without additional configuration
        var renderer = new ChromePdfRenderer();

        var pdf = renderer.RenderHtmlAsPdf(htmlContent);

        return File(pdf.BinaryData, "application/pdf", "document.pdf");
    }
}

API Reference

For complete documentation on Linux deployment:

• ChromePdfRenderer
• Docker and Linux Guide
• Linux Installation

Migration Considerations

Licensing

IronPDF operates under a commercial license model:

• Free development and testing with watermark
• Licensed versions for production use
• Perpetual licenses available
• Licensing details

API Differences

Migrating from SelectPdf requires code changes:

SelectPdf	IronPDF
HtmlToPdf	ChromePdfRenderer
PdfDocument	PdfDocument
SelectPdf.Converter.ConvertUrl()	renderer.RenderUrlAsPdf()
SelectPdf.Converter.ConvertHtmlString()	renderer.RenderHtmlAsPdf()

Most migrations involve updating class names and method calls. The conceptual approach remains similar.

What You Gain

• Native Linux, macOS, and Windows support
• Docker container compatibility
• Azure App Service Linux deployment
• AWS Lambda support
• Kubernetes deployment capability
• Consistent behavior across platforms

What to Consider

• Commercial license required for production
• Package size is larger than SelectPdf due to embedded Chromium
• Initial render may take slightly longer as Chromium initializes

Conclusion

SelectPdf does not support Linux and there is no workaround available. The Unable to load kernel32.dll error indicates a fundamental platform limitation. Developers requiring PDF generation on Linux environments need to evaluate alternative libraries. IronPDF provides cross-platform support with native Linux compatibility, eliminating platform-related deployment failures.

---

Jacob Mellor originally built IronPDF and leads technical development at Iron Software.

---

References

1. SelectPdf GitHub Issue #2: Linux Support{:rel="nofollow"} - Original report of Linux incompatibility
2. IronPDF Docker and Linux Documentation - Official guide for Linux deployment
3. IronPDF Linux Installation Guide - Platform-specific setup instructions

For the latest IronPDF documentation and tutorials, visit ironpdf.com.