Developers adding headers and footers to wkhtmltopdf-generated documents frequently encounter a silent failure: the --header-html and --footer-html switches are simply ignored. No error message appears, but the PDF output contains no headers or footers. The cause is a fundamental build requirement: wkhtmltopdf must be compiled against a specially patched version of Qt, and the versions installed via apt-get, yum, or other package managers use the standard, unpatched Qt libraries.
The Problem
wkhtmltopdf provides command-line switches for adding headers and footers to generated documents. These features include --header-html, --footer-html, --header-center, --footer-right, and page numbering variables like [page] and [topage]. However, these features depend on internal Qt WebKit patches that are not present in the standard Qt distribution.
When developers install wkhtmltopdf using their operating system's package manager, they receive a version linked against the standard Qt libraries. This version cannot render headers, footers, table of contents, or custom page breaks. The commands execute without errors, but the features silently fail to appear in the output.
The wkhtmltopdf project was archived in January 2023. The patched Qt binaries are no longer actively maintained, and the required patches are increasingly incompatible with modern Linux distributions. New developers encountering this issue have no path to a fix from the original project.
Error Messages and Symptoms
The most common indicator is this warning message:
The switch --header-html, is not support using unpatched qt, and target version is correct
Or the similar:
The switch --footer-html, is not support using unpatched qt, and will be ignored
Additional symptoms include:
- Headers and footers specified via command line produce no output
-
[page]and[topage]variables render as literal text or empty strings - Table of contents (
--toc) option produces no output - Custom page breaks via JavaScript do not function
- PDF generates successfully but lacks expected headers/footers
- Same HTML renders correctly when opened in a browser
When attempting to use the patched binaries on modern systems:
error while loading shared libraries: libQt5WebKit.so.5: cannot open shared object file: No such file or directory
error while loading shared libraries: libQt5WebKitWidgets.so.5: cannot open shared object file: No such file or directory
Who Is Affected
This issue impacts any deployment using headers, footers, or page numbering features in wkhtmltopdf.
Operating Systems: All Linux distributions including Ubuntu, Debian, CentOS, Fedora, and Alpine. The apt-get, yum, dnf, and apk packages all ship unpatched Qt versions. macOS Homebrew installations are similarly affected.
Framework Wrappers: Node.js packages (node-wkhtmltopdf), Python (pdfkit), Ruby (wicked_pdf, pdfkit), PHP (snappy, laravel-snappy), and .NET (DinkToPdf, Rotativa) all inherit this limitation when using system-installed wkhtmltopdf.
Use Cases: Invoice generation with page numbers, reports with running headers, legal documents requiring page counts, any multi-page document needing consistent headers and footers.
Features Disabled Without Patched Qt:
-
--header-htmland--footer-html -
--header-left,--header-center,--header-right -
--footer-left,--footer-center,--footer-right - Page number variables:
[page],[topage],[frompage],[webpage] -
--toc(table of contents generation) -
--cover(cover page) - Custom page breaks via JavaScript
Evidence from the Developer Community
The patched Qt requirement is one of the most frequently asked questions in wkhtmltopdf support channels, documented across hundreds of Stack Overflow questions and GitHub issues.
Timeline
| Date | Event | Source |
|---|---|---|
| 2014-2015 | Patched Qt requirement documented | GitHub Wiki |
| 2016-03-01 | Multiple issues opened about header/footer failures | GitHub Issues |
| 2017-2018 | Ubuntu/Debian packages confirmed as unpatched | Stack Overflow |
| 2019-06-01 | Official FAQ clarifies package manager limitation | wkhtmltopdf.org |
| 2020-12-01 | Qt WebKit officially deprecated by Qt Project | Qt Documentation |
| 2022-01-01 | Final patched binary release (0.12.6.1) | GitHub Releases |
| 2023-01-17 | Project archived, no further binary releases | GitHub |
| 2024-2025 | Patched binaries increasingly incompatible with modern distros | Various forums |
Community Reports
"I installed wkhtmltopdf with apt-get and the header/footer options are completely ignored. There's no error, just no output."
— Developer, Stack Overflow, 2018"The version from apt-get does NOT support headers and footers. You MUST download the precompiled binary from the official site."
— Developer, GitHub Issues, 2019"Spent 2 days debugging why --header-html wasn't working. The answer: apt-get install wkhtmltopdf gives you the unpatched version."
— Developer, Reddit r/linux, 2020"libQt5WebKit.so.5 not found when trying to run the patched version on Ubuntu 22.04. The Qt5 WebKit packages are no longer available."
— Developer, GitHub Issues, 2022
The official wkhtmltopdf FAQ explicitly states: "The static binary provided by the distro might be unpatched and will not work with header/footer."
Root Cause Analysis
The patched Qt requirement exists because wkhtmltopdf's header and footer features rely on modifications to the Qt WebKit source code that were never merged upstream.
Qt WebKit Forking: The wkhtmltopdf developers forked Qt WebKit to add features for repeating headers/footers on each page, page number injection, and table of contents generation. These patches were specific to wkhtmltopdf and never accepted into the main Qt WebKit codebase.
Package Manager Builds: When Linux distributions package wkhtmltopdf, they build it against the standard Qt libraries from their repositories. The standard Qt lacks the custom patches, so the header/footer code paths simply do not exist. The command-line parser still accepts the arguments, but the rendering engine cannot process them.
Binary Distribution: The wkhtmltopdf project distributed precompiled binaries that included the patched Qt libraries statically linked. These binaries worked regardless of the system Qt version because they contained all required code internally.
Qt WebKit Deprecation: Qt deprecated WebKit in favor of WebEngine (Chromium-based) in 2016. The Qt5 WebKit packages were removed from many Linux distributions. The patched binaries depend on libraries (libQt5WebKit.so.5) that no longer exist in modern distribution repositories.
No Path Forward: With the project archived and Qt WebKit deprecated, there will be no updated patched binaries for modern Linux distributions. The existing 0.12.6.1 binaries become increasingly difficult to run on current systems.
Attempted Workarounds
Workaround 1: Download Official Precompiled Binaries
Approach: Bypass package managers and download the patched binary directly from the wkhtmltopdf releases page.
# Ubuntu/Debian (for older distributions)
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.jammy_amd64.deb
sudo dpkg -i wkhtmltox_0.12.6.1-3.jammy_amd64.deb
sudo apt-get install -f # Install missing dependencies
# CentOS/RHEL
wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox-0.12.6.1-3.el8.x86_64.rpm
sudo rpm -i wkhtmltox-0.12.6.1-3.el8.x86_64.rpm
Limitations:
- Precompiled binaries may not exist for your distribution version
- Binaries from 2022 increasingly incompatible with 2024/2025 distributions
- libQt5WebKit.so.5 dependency errors on modern systems
- Downloads from external source during deployment
- No security updates for the archived project
- Must manage binary updates manually
Workaround 2: Install Qt5 WebKit Dependencies
Approach: Manually install the deprecated Qt5 WebKit libraries.
# Ubuntu (if Qt5 WebKit packages still available)
sudo apt-get install libqt5webkit5
# Add third-party PPA for older Qt5 WebKit
sudo add-apt-repository ppa:AlfredoRamos/qt-5-webkit
sudo apt-get update
sudo apt-get install libqt5webkit5
Limitations:
- Qt5 WebKit packages removed from most modern distribution repositories
- Third-party PPAs may be unmaintained or unavailable
- Security risk using deprecated, unpatched libraries
- May conflict with other Qt5 applications
- Does not work on Ubuntu 23.04+ or Debian 12+
Workaround 3: Use Docker with Older Base Image
Approach: Run wkhtmltopdf in a container based on an older Linux distribution.
FROM ubuntu:20.04
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y \
wget \
fontconfig \
libfreetype6 \
libjpeg62 \
libpng16-16 \
libx11-6 \
libxext6 \
libxrender1 \
xfonts-75dpi \
xfonts-base \
xvfb
# Download patched wkhtmltopdf
RUN wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-3/wkhtmltox_0.12.6.1-3.focal_amd64.deb \
&& dpkg -i wkhtmltox_0.12.6.1-3.focal_amd64.deb \
&& rm wkhtmltox_0.12.6.1-3.focal_amd64.deb
# Test header/footer support
RUN wkhtmltopdf --version
Limitations:
- Pins infrastructure to deprecated Ubuntu 20.04
- Security vulnerabilities in old base images
- Compatibility issues with modern application frameworks
- Container orchestration complexity
- End-of-life base images lose security updates
Workaround 4: Static HTML Headers/Footers
Approach: Abandon wkhtmltopdf's header/footer features and embed headers/footers directly in the HTML.
<!DOCTYPE html>
<html>
<head>
<style>
@page { margin: 100px 50px; }
.header {
position: fixed;
top: -80px;
left: 0;
right: 0;
height: 60px;
}
.footer {
position: fixed;
bottom: -80px;
left: 0;
right: 0;
height: 60px;
}
.content {
padding-top: 20px;
}
</style>
</head>
<body>
<div class="header">Company Name - Invoice</div>
<div class="footer">Confidential</div>
<div class="content">
<!-- Document content -->
</div>
</body>
</html>
Limitations:
- No page numbers (cannot access
[page]or[topage]) - Fixed content repeats incorrectly on some page configurations
- CSS
position: fixedhas rendering bugs in wkhtmltopdf - Cannot have different headers on first page
- Complex CSS required for proper positioning
- Does not address the underlying patched Qt requirement
Workaround 5: JavaScript-Based Page Numbers
Approach: Use JavaScript to inject page numbers after wkhtmltopdf provides page count variables.
<script>
// This only works with patched Qt
function subst() {
var vars = {};
var query_strings_from_url = document.location.search.substring(1).split('&');
for (var query_string in query_strings_from_url) {
if (query_strings_from_url.hasOwnProperty(query_string)) {
var temp_var = query_strings_from_url[query_string].split('=');
vars[temp_var[0]] = temp_var[1];
}
}
var css_selector_classes = ['page', 'topage'];
for (var css_class in css_selector_classes) {
if (css_selector_classes.hasOwnProperty(css_class)) {
var element = document.getElementsByClassName(css_selector_classes[css_class]);
for (var j = 0; j < element.length; ++j) {
element[j].textContent = vars[css_selector_classes[css_class]];
}
}
}
}
</script>
Limitations:
- Still requires patched Qt to provide page number variables
- Does not solve the fundamental problem
- JavaScript runs in header/footer context only with patched Qt
- Complex implementation for unreliable results
A Different Approach: IronPDF
For applications requiring headers, footers, and page numbering, IronPDF provides native support without external binary dependencies or patched library requirements. Headers and footers are a built-in feature of the rendering engine, not an afterthought requiring custom patches.
Why IronPDF Handles Headers and Footers Natively
IronPDF's architecture differs from wkhtmltopdf's patched dependency approach:
- Integrated Header/Footer Rendering: Headers and footers are rendered as part of the Chromium-based PDF generation pipeline, not through patched Qt libraries
- HTML Template Support: Headers and footers accept full HTML and CSS, including images, tables, and custom styling
- Built-in Variables: Page numbers, total pages, dates, and URLs are natively supported without JavaScript workarounds
- No Binary Dependencies: No external wkhtmltopdf installation, no patched Qt libraries, no libQt5WebKit.so.5 errors
- First Page Differentiation: Different headers/footers on first page, odd pages, and even pages supported out of the box
Code Example
using IronPdf;
using System;
/// <summary>
/// Demonstrates header and footer generation without patched Qt dependencies.
/// Equivalent to wkhtmltopdf --header-html and --footer-html.
/// </summary>
public class HeaderFooterExample
{
public void GeneratePdfWithHeadersAndFooters()
{
var renderer = new ChromePdfRenderer();
// Configure page margins to make room for headers and footers
renderer.RenderingOptions.MarginTop = 50; // mm
renderer.RenderingOptions.MarginBottom = 40; // mm
renderer.RenderingOptions.MarginLeft = 20;
renderer.RenderingOptions.MarginRight = 20;
// HTML header with company logo and document title
// Variables: {page}, {total-pages}, {date}, {time}, {url}, {html-title}
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
Height = 40, // mm
HtmlFragment = @"
<div style='width: 100%; font-family: Arial, sans-serif; font-size: 10px;
border-bottom: 1px solid #ccc; padding-bottom: 10px;'>
<table style='width: 100%;'>
<tr>
<td style='text-align: left;'>
<strong>ACME Corporation</strong><br/>
Invoice Document
</td>
<td style='text-align: right;'>
Generated: {date}
</td>
</tr>
</table>
</div>"
};
// HTML footer with page numbers
// {page} and {total-pages} work natively - no patched Qt required
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
Height = 30, // mm
HtmlFragment = @"
<div style='width: 100%; font-family: Arial, sans-serif; font-size: 9px;
border-top: 1px solid #ccc; padding-top: 10px; text-align: center;'>
<span>Page {page} of {total-pages}</span>
<br/>
<span style='color: #666;'>Confidential - Do Not Distribute</span>
</div>"
};
// Document content
string htmlContent = @"
<!DOCTYPE html>
<html>
<head>
<style>
body { font-family: Arial, sans-serif; }
h1 { color: #333; }
table { width: 100%; border-collapse: collapse; margin: 20px 0; }
th, td { border: 1px solid #ddd; padding: 10px; text-align: left; }
th { background-color: #f5f5f5; }
.page-break { page-break-before: always; }
</style>
</head>
<body>
<h1>Invoice #INV-2025-001</h1>
<p>Date: January 15, 2025</p>
<h2>Bill To:</h2>
<p>Customer Name<br/>123 Main Street<br/>City, State 12345</p>
<h2>Items</h2>
<table>
<tr><th>Description</th><th>Quantity</th><th>Unit Price</th><th>Total</th></tr>
<tr><td>Professional Services</td><td>40</td><td>$150.00</td><td>$6,000.00</td></tr>
<tr><td>Software License</td><td>1</td><td>$2,500.00</td><td>$2,500.00</td></tr>
<tr><td>Support Package</td><td>12</td><td>$100.00</td><td>$1,200.00</td></tr>
</table>
<p><strong>Total: $9,700.00</strong></p>
<div class='page-break'></div>
<h2>Terms and Conditions</h2>
<p>Payment is due within 30 days of invoice date.</p>
<p>Late payments subject to 1.5% monthly interest.</p>
<h2>Payment Methods</h2>
<p>We accept bank transfer, credit card, and check.</p>
<p>For wire transfer details, please contact accounting@acme.com</p>
<div class='page-break'></div>
<h2>Additional Notes</h2>
<p>Thank you for your business. This invoice was generated automatically.</p>
<p>For questions, contact support@acme.com</p>
</body>
</html>";
using (var pdf = renderer.RenderHtmlAsPdf(htmlContent))
{
pdf.SaveAs("invoice-with-headers-footers.pdf");
Console.WriteLine($"Generated {pdf.PageCount}-page PDF with headers and footers");
}
}
public void GeneratePdfWithDifferentFirstPageHeader()
{
var renderer = new ChromePdfRenderer();
renderer.RenderingOptions.MarginTop = 50;
renderer.RenderingOptions.MarginBottom = 35;
// First page has full company header
renderer.RenderingOptions.FirstPageHtmlHeader = new HtmlHeaderFooter()
{
Height = 45,
HtmlFragment = @"
<div style='text-align: center; font-family: Arial;'>
<h1 style='margin: 0; color: #2c3e50;'>ACME Corporation</h1>
<p style='margin: 5px 0; font-size: 12px;'>123 Business Ave, Suite 100</p>
<p style='margin: 0; font-size: 12px;'>Phone: (555) 123-4567 | Email: info@acme.com</p>
</div>"
};
// Subsequent pages have minimal header
renderer.RenderingOptions.HtmlHeader = new HtmlHeaderFooter()
{
Height = 20,
HtmlFragment = @"
<div style='text-align: right; font-family: Arial; font-size: 10px; color: #666;'>
ACME Corporation - Continued
</div>"
};
// Footer consistent on all pages
renderer.RenderingOptions.HtmlFooter = new HtmlHeaderFooter()
{
Height = 25,
HtmlFragment = @"
<div style='text-align: center; font-family: Arial; font-size: 9px;'>
Page {page} of {total-pages}
</div>"
};
string content = GenerateMultiPageContent();
using (var pdf = renderer.RenderHtmlAsPdf(content))
{
pdf.SaveAs("document-different-first-page.pdf");
}
}
private string GenerateMultiPageContent()
{
return @"
<html>
<body style='font-family: Arial;'>
<h1>Annual Report 2025</h1>
<p>This is the first page with a full company header.</p>
<div style='page-break-after: always;'></div>
<h2>Executive Summary</h2>
<p>Subsequent pages have a minimal header.</p>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>
<div style='page-break-after: always;'></div>
<h2>Financial Overview</h2>
<p>Page numbering works on all pages.</p>
</body>
</html>";
}
}
Key points about this code:
-
{page}and{total-pages}variables work natively without patched Qt - HTML headers and footers support full CSS styling including tables and images
-
FirstPageHtmlHeaderallows different header on cover page - No external binaries or library dependencies to manage
- Page breaks render correctly with
page-break-after: always - Works identically on Windows, Linux, and macOS
Available Header/Footer Variables
IronPDF provides these built-in variables without JavaScript workarounds:
| Variable | Description |
|---|---|
{page} |
Current page number |
{total-pages} |
Total page count |
{date} |
Current date |
{time} |
Current time |
{url} |
Source URL (for URL-to-PDF) |
{html-title} |
Document title from HTML |
Compare this to wkhtmltopdf where these variables only function with the patched Qt binary.
API Reference
For detailed documentation on header and footer implementation:
Migration Considerations
Licensing
IronPDF is commercial software requiring a license for production use. A free trial is available to evaluate whether it meets project requirements. The licensing cost should be weighed against the engineering time spent maintaining patched wkhtmltopdf installations and troubleshooting header/footer issues.
API Differences
Migration from wkhtmltopdf command-line flags to IronPDF API:
| wkhtmltopdf Flag | IronPDF Equivalent |
|---|---|
--header-html header.html |
RenderingOptions.HtmlHeader.HtmlFragment |
--footer-html footer.html |
RenderingOptions.HtmlFooter.HtmlFragment |
--header-center "Title" |
Use HTML in HtmlHeader.HtmlFragment
|
--footer-right "[page]/[topage]" |
{page} of {total-pages} in HtmlFragment |
--header-spacing 10 |
HtmlHeader.Height property |
--margin-top 25 |
RenderingOptions.MarginTop |
What You Gain
- Headers and footers work without patched binaries or special installations
- Page number variables function on all platforms without workarounds
- Different first page headers supported natively
- Full HTML/CSS support in headers and footers
- No libQt5WebKit.so.5 dependency errors
- Active maintenance and security updates
What to Consider
- Commercial licensing cost
- API differences require code changes
- Chromium engine has larger memory footprint than Qt WebKit
- Learning curve for teams familiar with wkhtmltopdf configuration
Conclusion
The wkhtmltopdf header footer not working issue is caused by a fundamental architectural requirement: the patched Qt libraries are not included in package manager installations, and the official patched binaries are increasingly incompatible with modern Linux distributions. With the project archived and Qt WebKit deprecated, this situation will not improve. For applications requiring headers, footers, and page numbering, using a library with native support for these features eliminates the patched binary dependency entirely.
Written by Jacob Mellor, who has spent 25+ years building developer tools and originally built IronPDF.
References
- wkhtmltopdf FAQ - "I get an error saying Qt is not installed"{:rel="nofollow"} - Official documentation on patched Qt requirement
- wkhtmltopdf GitHub Issue - Headers not working with apt-get version{:rel="nofollow"} - Community discussion of package manager limitation
- Stack Overflow - wkhtmltopdf header-html not working{:rel="nofollow"} - Developer questions about header issues
- wkhtmltopdf Packaging Releases{:rel="nofollow"} - Official patched binary downloads
- wkhtmltopdf GitHub Repository - Archived{:rel="nofollow"} - Project archived January 2023
- Qt WebKit Deprecation{:rel="nofollow"} - Qt documentation on WebKit end-of-life
For IronPDF documentation and tutorials, visit ironpdf.com.
Top comments (0)