HTML to PDF API Comparison: WeasyPrint vs wkhtmltopdf — When to Use Which

PdfBroker.io is a cloud-based PDF generation REST API that offers two distinct HTML-to-PDF rendering engines: WeasyPrint and wkhtmltopdf. Both accept HTML and CSS input and return a PDF document, but they work very differently under the hood. This article compares the two services across rendering quality, CSS support, compliance capabilities, performance, and pricing so you can choose the right one for your project.

Quick Comparison

How They Render

WeasyPrint — Document-First

WeasyPrint is a purpose-built PDF engine that treats HTML and CSS as a page description language. It excels at producing print-quality documents with precise control over pagination, headers, footers, and page numbering.

WeasyPrint's rendering approach:

• Implements CSS Paged Media (the W3C specification for printed documents)
• Supports @page rules with named pages, margin boxes, and page counters
• Handles page-break-before, page-break-after, and page-break-inside properties
• Does not execute JavaScript — the HTML and CSS are rendered as-is
• Uses its own layout engine, not a browser

This makes WeasyPrint ideal when you design templates specifically for PDF output. You control exactly how content flows across pages.

wkhtmltopdf — Browser-First

wkhtmltopdf uses a WebKit rendering engine — essentially a headless browser — to render HTML the same way Chrome or Safari would display it, and then "prints" the result to PDF.

wkhtmltopdf's rendering approach:

• Renders HTML exactly as a browser would, including JavaScript execution
• Good at capturing web pages as they appear on screen
• Supports browser-era CSS (flexbox, grid, animations — though animations are frozen)
• JavaScript runs before PDF generation, so dynamic content (charts, client-side templates) works
• Pagination is automatic but less controllable than WeasyPrint

This makes wkhtmltopdf a good choice when you want to convert an existing web page to PDF, or when your content depends on JavaScript for rendering.

CSS Support Comparison

CSS Paged Media (WeasyPrint advantage)

WeasyPrint's strongest feature is its CSS Paged Media support. This allows you to define page-specific layout rules directly in CSS:

@page {
  size: A4;
  margin: 25mm 20mm;

  @top-center {
    content: "Company Report — Confidential";
    font-size: 9px;
    color: #999;
  }

  @bottom-right {
    content: "Page " counter(page) " of " counter(pages);
    font-size: 9px;
    color: #999;
  }
}

@page :first {
  @top-center { content: none; }  /* No header on first page */
}

h1 { page-break-before: always; }
table { page-break-inside: avoid; }

This level of print control is not available in wkhtmltopdf.

JavaScript Support (wkhtmltopdf advantage)

wkhtmltopdf executes JavaScript, which means you can use client-side libraries:

<!-- This works in wkhtmltopdf but NOT in WeasyPrint -->
<div id="chart"></div>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
  new Chart(document.getElementById('chart'), {
    type: 'bar',
    data: {
      labels: ['Q1', 'Q2', 'Q3', 'Q4'],
      datasets: [{ label: 'Revenue', data: [120, 190, 170, 210] }]
    }
  });
</script>

If your content relies on JavaScript rendering, wkhtmltopdf is the only option on PdfBroker.io.

PDF/A and PDF/UA Compliance

This is a clear differentiator. Only WeasyPrint supports PDF/A and PDF/UA on PdfBroker.io.

If you need archival compliance (PDF/A) or accessibility compliance (PDF/UA) — for example to meet the European Accessibility Act requirements — WeasyPrint is the required choice. Add the compliance variant via the pdf-variant argument:

{
  "htmlBase64String": "<base64-encoded HTML>",
  "weasyPrintToPdfArguments": {
    "pdf-variant": "pdf/ua-1"
  }
}

See the full guide: Getting Started with PDF/A and PDF/UA Compliance via API.

URL-Based Generation

Both engines can generate a PDF from a URL. This is useful for converting existing web pages.

WeasyPrint from URL

POST https://api.pdfbroker.io/api/pdf/weasyprint

{
  "url": "https://www.example.com/report"
}

wkhtmltopdf from URL

POST https://api.pdfbroker.io/api/pdf/wkhtmltopdf

{
  "url": "https://www.example.com/report",
  "wkHtmlToPdfArguments": {
    "page-size": "A4",
    "margin-top": "10mm",
    "margin-bottom": "10mm"
  }
}

wkhtmltopdf provides more command-line style arguments for controlling the output (margins, page size, headers/footers via HTML snippets). See the wkhtmltopdf documentation for the full argument list.

Including Images and Resources

WeasyPrint — Resources Object

WeasyPrint supports a resources object where you can pass images, fonts, and other assets as base64-encoded files. These are referenced by filename in your HTML:

{
  "htmlBase64String": "<base64 HTML referencing logo.png>",
  "resources": {
    "logo.png": "<base64-encoded image>"
  }
}

See the Images in HTML Templates documentation for details.

wkhtmltopdf — URL References

wkhtmltopdf loads resources the way a browser does — via URLs. If your HTML references https://example.com/logo.png, wkhtmltopdf will fetch it during rendering. For base64-encoded inline content, embed images directly using data URIs in your HTML.

Pricing

wkhtmltopdf is available on all plans, including the free tier. WeasyPrint requires a Basic plan or above. New accounts receive a 14-day trial of premium services. See the full Pricing page.

Decision Guide

Choose WeasyPrint when you:

• Are creating documents designed specifically for PDF output (invoices, reports, certificates)
• Need PDF/A for archival or PDF/UA for accessibility compliance
• Want precise control over pagination, headers, footers, and page numbering via CSS
• Are building templates with the PdfBroker Template Tool
• Do not need JavaScript execution in your templates

Choose wkhtmltopdf when you:

• Want to convert an existing web page to PDF
• Your content relies on JavaScript for rendering (charts, dynamic content)
• You are on the free plan and evaluating PdfBroker.io
• You need browser-style rendering fidelity (the PDF should look like the browser output)
• You are migrating from a local wkhtmltopdf installation to a cloud API

Use both when you:

• Have different document types with different requirements (e.g., invoices via WeasyPrint, web page snapshots via wkhtmltopdf)
• Want to prototype on the free tier with wkhtmltopdf and upgrade to WeasyPrint for production

Code Examples: Same Template, Both Engines

Here is the same invoice template rendered through both engines, so you can see the API differences:

WeasyPrint

using PdfBroker.Client;
using PdfBroker.Common.RequestObjects;

var client = new PdfBrokerClientService("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

var html = await File.ReadAllTextAsync("invoice.html");

var request = new WeasyPrintRequestDto
{
    HtmlBase64String = Convert.ToBase64String(
        System.Text.Encoding.UTF8.GetBytes(html)),
    WeasyPrintToPdfArguments = new Dictionary<string, string>
    {
        { "pdf-variant", "pdf/a-3b" }
    }
};

byte[] pdf = await client.WeasyPrintAsByteArrayAsync(request);
await File.WriteAllBytesAsync("invoice-weasyprint.pdf", pdf);

wkhtmltopdf

using PdfBroker.Client;
using PdfBroker.Common.RequestObjects;

var client = new PdfBrokerClientService("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

var html = await File.ReadAllTextAsync("invoice.html");

var request = new WkHtmlToPdfRequestDto
{
    HtmlBase64String = Convert.ToBase64String(
        System.Text.Encoding.UTF8.GetBytes(html)),
    WkHtmlToPdfArguments = new Dictionary<string, string>
    {
        { "page-size", "A4" },
        { "margin-top", "15mm" },
        { "margin-bottom", "15mm" }
    }
};

byte[] pdf = await client.WkHtmlToPdfAsByteArrayAsync(request);
await File.WriteAllBytesAsync("invoice-wkhtmltopdf.pdf", pdf);

The key difference: WeasyPrint uses WeasyPrintRequestDto and WeasyPrintToPdfArguments, while wkhtmltopdf uses WkHtmlToPdfRequestDto and WkHtmlToPdfArguments. The HTML template and base64 encoding work the same way for both.

Summary

PdfBroker.io gives you two HTML-to-PDF engines, each suited to different tasks. WeasyPrint is the recommended choice for document generation workflows where you control the template — it offers superior print layout control and is the only option for PDF/A and PDF/UA compliance. wkhtmltopdf is the right choice for converting existing web content or JavaScript-rendered pages to PDF, and is available on the free tier for evaluation.

Related Resources

• WeasyPrint as a Service — Full WeasyPrint API reference
• wkhtmltopdf as a Service — Full wkhtmltopdf API reference
• Getting Started with PDF/A and PDF/UA Compliance via API — Compliance guide
• How to Generate PDF Invoices from HTML with a REST API — Practical WeasyPrint tutorial
• Images in HTML Templates — Resource handling for both engines
• Pricing — Plan comparison