DEV Community

IronSoftware
IronSoftware

Posted on

Using WeasyPrint from .NET: Python Interop Challenges and Alternatives

#csharp #dotnet

Developers building .NET applications sometimes consider WeasyPrint for HTML-to-PDF conversion. WeasyPrint is a Python library that converts HTML and CSS into PDF documents, and it has earned a reputation for producing clean, standards-compliant output. However, using WeasyPrint from C# or .NET introduces significant complexity. The library was not designed for the .NET ecosystem, and integrating it requires either Python runtime management, process spawning, or third-party wrapper packages that embed over 100 MB of dependencies.

This article examines the technical challenges of using WeasyPrint from .NET, documents common issues developers encounter, and presents IronPDF as a native .NET alternative that eliminates the Python interop complexity.

The Problem

WeasyPrint is written entirely in Python. It does not offer native bindings for C#, .NET, or any other runtime outside the Python ecosystem. For .NET developers, this creates a fundamental integration problem: how do you call a Python library from a C# application?

The options available are:

  1. Shell out to Python: Spawn a Python process from .NET and invoke WeasyPrint as a command-line tool
  2. Use Python.NET interop: Load the Python runtime into your .NET process and call WeasyPrint directly
  3. Use a third-party wrapper: Install a NuGet package that embeds Python and WeasyPrint together

Each approach introduces its own set of complications. None of them provide the straightforward experience of installing a native .NET library and calling its API directly.

Shell Process Approach

The simplest integration method involves spawning a Python process from C#:

using System.Diagnostics;

public class WeasyPrintShellWrapper
{
    public byte[] ConvertHtmlToPdf(string htmlContent)
    {
        // Write HTML to a temporary file
        string tempHtmlPath = Path.GetTempFileName() + ".html";
        string tempPdfPath = Path.GetTempFileName() + ".pdf";

        try
        {
            File.WriteAllText(tempHtmlPath, htmlContent);

            // Spawn Python process to run WeasyPrint
            var process = new Process
            {
                StartInfo = new ProcessStartInfo
                {
                    FileName = "python",
                    Arguments = $"-m weasyprint \"{tempHtmlPath}\" \"{tempPdfPath}\"",
                    RedirectStandardError = true,
                    UseShellExecute = false,
                    CreateNoWindow = true
                }
            };

            process.Start();
            string errors = process.StandardError.ReadToEnd();
            process.WaitForExit();

            if (process.ExitCode != 0)
            {
                throw new Exception($"WeasyPrint failed: {errors}");
            }

            return File.ReadAllBytes(tempPdfPath);
        }
        finally
        {
            // Cleanup temporary files
            if (File.Exists(tempHtmlPath)) File.Delete(tempHtmlPath);
            if (File.Exists(tempPdfPath)) File.Delete(tempPdfPath);
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

This approach has multiple problems:

  • Python must be installed on every machine that runs the application
  • WeasyPrint must be installed via pip in the Python environment
  • GTK+ libraries must be present for WeasyPrint to function on Windows
  • Path configuration must be correct for the process to find Python and its packages
  • Temporary file management creates cleanup responsibilities and potential security issues
  • Error handling becomes complicated when errors occur in external processes
  • Performance overhead from process spawning affects high-volume scenarios

Python.NET Interop Approach

A more sophisticated approach uses Python.NET to load the Python runtime directly into the .NET process. This eliminates process spawning but introduces different complications:

using Python.Runtime;

public class WeasyPrintPythonNetWrapper
{
    public byte[] ConvertHtmlToPdf(string htmlContent)
    {
        // Initialize Python runtime (once per application lifecycle)
        PythonEngine.Initialize();

        using (Py.GIL()) // Acquire Global Interpreter Lock
        {
            dynamic weasyprint = Py.Import("weasyprint");
            dynamic html = weasyprint.HTML(@string: htmlContent);

            // Write to bytes
            using (var stream = new MemoryStream())
            {
                byte[] pdfBytes = html.write_pdf();
                return pdfBytes;
            }
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

The Python.NET approach requires:

  • Python runtime installed and configured correctly
  • Python.NET NuGet package which has its own compatibility requirements
  • Global Interpreter Lock (GIL) management, which affects threading
  • Python environment configuration at runtime
  • All WeasyPrint dependencies still need to be installed

Both approaches share a fundamental limitation: they require Python and its ecosystem to be present on the deployment target.

Deployment Complexity

The deployment story for WeasyPrint in .NET applications is where most teams encounter significant friction. WeasyPrint has native dependencies that vary by operating system.

Windows Dependencies

On Windows, WeasyPrint requires:

  • Python 3.x runtime
  • GTK+ 3.x libraries (Pango, Cairo, GDK-Pixbuf)
  • Proper PATH configuration so Python can locate these libraries

The WeasyPrint documentation recommends installing GTK+ via MSYS2:

# In MSYS2 shell
pacman -S mingw-w64-x86_64-pango
Enter fullscreen mode Exit fullscreen mode

After installation, developers must add the GTK bin folder to the system PATH, or set the WEASYPRINT_DLL_DIRECTORIES environment variable to point to the library locations.

Common Windows errors include:

OSError: cannot load library 'gobject-2.0-0': error 0x7e
OSError: cannot load library 'pango-1.0-0': error 0x7e
distutils.errors.DistutilsPlatformError: Microsoft Visual C++ 14.0 is required
Enter fullscreen mode Exit fullscreen mode

These errors indicate missing native dependencies that must be installed separately from the Python package.

Linux Dependencies

On Linux, WeasyPrint requires system packages:

# Debian/Ubuntu
apt-get install python3 python3-pip python3-cffi python3-brotli \
    libpango-1.0-0 libpangoft2-1.0-0 libpangocairo-1.0-0

# RHEL/CentOS/Fedora
yum install python3 python3-pip python3-cffi pango
Enter fullscreen mode Exit fullscreen mode

Docker Deployment

Docker deployments require explicit installation of all dependencies in the Dockerfile:

FROM python:3.11-slim

# Install WeasyPrint system dependencies
RUN apt-get update && apt-get install -y \
    libpango-1.0-0 \
    libpangoft2-1.0-0 \
    libpangocairo-1.0-0 \
    libgdk-pixbuf2.0-0 \
    libffi-dev \
    && rm -rf /var/lib/apt/lists/*

# Install WeasyPrint
RUN pip install weasyprint

# Your .NET application would need to call this Python installation
Enter fullscreen mode Exit fullscreen mode

For .NET applications, this means maintaining a mixed Docker image with both .NET and Python runtimes, increasing image size and complexity.

Third-Party .NET Wrappers

To address the deployment complexity, several developers have created NuGet packages that bundle WeasyPrint with its dependencies.

Weasyprint.Wrapped

The Weasyprint.Wrapped{:rel="nofollow"} package embeds a standalone Python installation along with WeasyPrint and GTK+ libraries. This eliminates the need to install Python separately, but introduces other issues.

using Weasyprint.Wrapped;

public class WeasyPrintWrappedExample
{
    public async Task GeneratePdf()
    {
        // Initialize extracts ~104 MB of bundled files on first run
        var printer = new WeasyPrinter();
        await printer.Initialize();

        string html = "<html><body><h1>Hello World</h1></body></html>";
        byte[] pdfBytes = await printer.PrintToPdf(html);

        File.WriteAllBytes("output.pdf", pdfBytes);
    }
}
Enter fullscreen mode Exit fullscreen mode

Package characteristics:

  • Approximately 104 MB of compressed resources for Windows
  • Approximately 89.7 MB of compressed resources for Linux
  • First initialization extracts files to disk
  • Contains standalone Python 3.x, GTK3, and WeasyPrint

Known issues from the package documentation:

"Note that this is a large package, try to limit the projects where it will be installed."

The package must extract its embedded files to disk before first use. This creates problems in certain deployment scenarios:

Balbarak.WeasyPrint

Balbarak.WeasyPrint{:rel="nofollow"} is another .NET wrapper that bundles Python and WeasyPrint. It targets Windows specifically and has accumulated several open issues.

Documented issues:

Issue Description Status
#5{:rel="nofollow"} Access Denied error in IIS Open
#19{:rel="nofollow"} Running in Azure Function fails Open
#17{:rel="nofollow"} Permissions issue in IIS Open
#18{:rel="nofollow"} Error in IIS Windows Open
#3{:rel="nofollow"} JPG files not supported Open

The Access Denied issue (#5) illustrates a common deployment problem:

"I get the following error: 'Access to the path C:\WINDOWS\SysWOW64\inetsrv\weasyprint-v48 is denied' (System.UnauthorizedAccessException). Is there any idea how to fix this error?"

The underlying cause is that the wrapper needs to extract files to disk, but the IIS worker process typically does not have write access to the installation directory. The maintainer's response:

"The plugin needs to create folders on the project path. Use a location where the project can write files on disk."

This requirement conflicts with common deployment patterns where applications run from read-only locations or where the executing user has restricted permissions.

Azure and Cloud Deployment Issues

Cloud deployments present particular challenges for WeasyPrint in .NET applications.

Azure Functions

Azure Functions users have reported failures when deploying Python functions that use WeasyPrint. The error typically involves missing system libraries:

OSError: cannot load library 'libpango-1.0-0': libpango-1.0-0: cannot open shared object file: No such file or directory
Enter fullscreen mode Exit fullscreen mode

The Azure Functions Python runtime does not include GTK+ libraries by default. Users must either:

  1. Deploy a custom container image with the required libraries
  2. Use a premium plan that supports custom images
  3. Find an alternative library that does not require native GTK+ dependencies

Azure App Service

Azure App Service deployments face similar issues. The default Windows images do not include GTK+ libraries, and the default Linux images do not include the full set of WeasyPrint dependencies.

Read-Only File Systems

Many cloud platforms mount application code as read-only for security and consistency. The WeasyPrint wrappers that need to extract files to disk will fail in these environments:

System.UnauthorizedAccessException: Access to the path '/app/weasyprint' is denied.
Enter fullscreen mode Exit fullscreen mode

CSS and JavaScript Limitations

Beyond the deployment complexity, WeasyPrint has functional limitations that may affect certain use cases.

No JavaScript Support

WeasyPrint does not execute JavaScript. This is a fundamental architectural decision, not a bug. The library renders static HTML and CSS only.

Content that relies on JavaScript will not render:

  • Charts generated by JavaScript libraries (Chart.js, D3.js, Highcharts)
  • Dynamically loaded content
  • Single-page application (SPA) content
  • Any element populated after initial page load

From the WeasyPrint documentation:

"WeasyPrint is not a web browser and does not support JavaScript. If you need JavaScript execution, consider preprocessing your content with a headless browser."

CSS Support Limitations

WeasyPrint supports CSS Paged Media specifications, making it suitable for print-oriented layouts. However, it does not support all CSS features that modern browsers handle:

  • CSS Grid: Not fully supported
  • Flexbox: Limited support, may not match browser rendering
  • CSS Variables: Limited support
  • Experimental CSS features: Not implemented

For documents designed with web CSS frameworks like Bootstrap or Tailwind, rendering differences may occur.

Performance Considerations

WeasyPrint's Python-based layout engine can struggle with complex documents:

  • Large CSS frameworks increase processing time
  • Tables rendered across multiple pages are particularly slow
  • High numbers of CSS properties with many HTML elements cause cascade calculation delays

The documentation recommends:

"A high number of CSS properties with a high number of HTML tags can lead to a huge amount of time spent for the cascade. Avoiding large CSS frameworks can drastically reduce the rendering time."

A Different Approach: IronPDF

IronPDF provides a native .NET library for HTML-to-PDF conversion that eliminates the Python interop complexity entirely. The library is built for .NET and integrates directly with C# applications without requiring external runtimes or native dependency management.

Why IronPDF Avoids These Issues

IronPDF uses an embedded Chromium rendering engine rather than a Python-based layout engine. This architectural difference addresses the core challenges of WeasyPrint integration:

  • No Python runtime required: IronPDF is a pure .NET library
  • No GTK+ dependencies: The Chromium engine is self-contained
  • No file extraction on first run: The library loads directly from the NuGet package
  • Full JavaScript support: The Chromium engine executes JavaScript
  • Modern CSS support: Flexbox, Grid, CSS Variables, and modern CSS work correctly
  • Single NuGet package: Installation is Install-Package IronPdf

Code Example

The following example demonstrates HTML-to-PDF conversion with IronPDF. The code requires no external dependencies, Python installation, or special configuration.

using IronPdf;

public class IronPdfExample
{
    public void ConvertHtmlToPdf()
    {
        // Create a renderer instance
        var renderer = new ChromePdfRenderer();

        // Configure rendering options (optional)
        renderer.RenderingOptions.MarginTop = 10;
        renderer.RenderingOptions.MarginBottom = 10;
        renderer.RenderingOptions.EnableJavaScript = true;
        renderer.RenderingOptions.WaitFor.RenderDelay(500);

        // Convert HTML string to PDF
        string html = @"
            <html>
            <head>
                <style>
                    body { font-family: Arial, sans-serif; }
                    .container { display: flex; gap: 20px; }
                    .card {
                        border: 1px solid #ddd;
                        padding: 20px;
                        border-radius: 8px;
                    }
                </style>
            </head>
            <body>
                <h1>Invoice #12345</h1>
                <div class='container'>
                    <div class='card'>
                        <h3>Bill To:</h3>
                        <p>Customer Name</p>
                    </div>
                    <div class='card'>
                        <h3>Ship To:</h3>
                        <p>Shipping Address</p>
                    </div>
                </div>
            </body>
            </html>";

        PdfDocument pdf = renderer.RenderHtmlAsPdf(html);

        // Save to file
        pdf.SaveAs("invoice.pdf");
    }

    public byte[] ConvertUrlToPdf(string url)
    {
        var renderer = new ChromePdfRenderer();

        // Render any URL, including dynamic JavaScript content
        PdfDocument pdf = renderer.RenderUrlAsPdf(url);

        return pdf.BinaryData;
    }
}
Enter fullscreen mode Exit fullscreen mode

Key points about this code:

  • The ChromePdfRenderer class handles all rendering internally
  • JavaScript is executed by the embedded Chromium engine
  • Modern CSS features like Flexbox render correctly
  • No external process spawning or file extraction required
  • The code works identically on Windows, Linux, and macOS

Docker Deployment

IronPDF deployment in Docker is straightforward. The library includes Linux support without requiring Python or GTK+ installation:

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

# Install minimal IronPDF dependencies for Linux
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", "YourApplication.dll"]
Enter fullscreen mode Exit fullscreen mode

For simplified deployment, IronPDF also provides a pre-built Docker base image:

FROM ironsoftware/ironpdf:latest
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "YourApplication.dll"]
Enter fullscreen mode Exit fullscreen mode

Azure Deployment

IronPDF works in Azure App Service and Azure Functions without special configuration. The library does not require write access to the file system for extraction, and it does not depend on system libraries that must be pre-installed.

API Reference

For more details on the methods used:

Migration Considerations

Licensing

IronPDF is commercial software. Licenses are available for individual developers, teams, and enterprises. A free trial is available for evaluation. Developers should review the licensing terms at ironpdf.com before committing to migration.

API Differences

Migrating from WeasyPrint to IronPDF requires code changes. The APIs are different, and some WeasyPrint-specific CSS features (like CSS Paged Media extensions) may need adjustment. However, the migration typically simplifies the codebase by removing Python interop code, process management, and dependency configuration.

What You Gain

  • Native .NET integration without external runtime dependencies
  • Full JavaScript execution support
  • Modern CSS rendering (Flexbox, Grid, CSS Variables)
  • Simplified deployment to cloud platforms
  • No file extraction or permission issues
  • Commercial support

What to Consider

  • Commercial licensing costs
  • Learning the IronPDF API
  • Testing existing HTML templates for rendering differences
  • Evaluating the free trial before committing

Conclusion

Using WeasyPrint from .NET is technically possible but introduces significant complexity. The Python interop requirement, native GTK+ dependencies, and deployment challenges create friction that native .NET libraries avoid. For teams that need reliable HTML-to-PDF conversion in .NET applications, IronPDF provides a simpler path forward with better cloud deployment support and full JavaScript execution capabilities.

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

References

  1. WeasyPrint-netcore GitHub Repository{:rel="nofollow"} - .NET wrapper for WeasyPrint
  2. Weasyprint.Wrapped NuGet Package{:rel="nofollow"} - Standalone .NET wrapper with embedded dependencies
  3. WeasyPrint Documentation{:rel="nofollow"} - Official WeasyPrint documentation
  4. WeasyPrint For .Net on Windows - Issue #759{:rel="nofollow"} - Discussion of .NET integration options
  5. WeasyPrint Docker Issues{:rel="nofollow"} - CSS loading issues in Docker containers
  6. Adding WeasyPrint in Docker{:rel="nofollow"} - Docker community discussion
  7. Reddit: HTML to PDF library .NET 6.0{:rel="nofollow"} - Community discussion of PDF library options

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

Top comments (0)