How to Add Headers and Footers to wkhtmltopdf Output

wkhtmltopdf supports text in the left, center, and right positions of a repeating header or footer. For more layout control, it can use a separate HTML document as the header or footer. Set page margins and header/footer spacing as separate values so the page content and repeating elements have room.

The examples below use the command-line tool. Confirm option syntax and page-number substitution tokens with wkhtmltopdf --help and the manual installed with your version; the project references substitution sequences, but the complete token list is not included in its settings reference.

1. Add a simple text header and footer

Use the positional options for short labels, titles, dates, or other plain text. Header options go before the input page and output PDF in this example:

wkhtmltopdf \
  --header-left "Quarterly report" \
  --header-center "Example Company" \
  --header-right "Internal" \
  --footer-left "Prepared for review" \
  --footer-center "Page [page] of [toPage]" \
  --footer-right "Example Company" \
  --margin-top 25mm \
  --margin-bottom 20mm \
  https://example.com/report report.pdf

Page-number placeholders such as [page] and [toPage] are commonly used in wkhtmltopdf examples, but confirm supported substitution sequences for your installed build before relying on them. The project settings reference documents a pageOffset setting that adds a number to page numbers used in headers, footers, and the table of contents; it does not provide the full token list there.

Position, font, line, and spacing options

The settings family includes left, center, and right text, font size and name, a line option, and spacing. Footer settings have corresponding options. The exact command-line spelling can vary by version or wrapper, so check wkhtmltopdf --extended-help or the manual for the switches available in your installation. The underlying settings names include header.left, header.center, header.right, font settings, line, spacing, and header.htmlUrl; corresponding footer settings are available too.

2. Use an HTML document for a designed header or footer

When short positional text is not enough, provide a separate HTML document for the header or footer. This lets you maintain a small markup document for a logo, styled title, or structured content, subject to the rendering and resource support of your installed wkhtmltopdf build.

wkhtmltopdf \
  --header-html file:///absolute/path/header.html \
  --footer-html file:///absolute/path/footer.html \
  --margin-top 30mm \
  --margin-bottom 25mm \
  https://example.com/report report.pdf

Use absolute file URLs for local documents and verify that linked stylesheets, fonts, and images are reachable by the process that runs wkhtmltopdf. Confirm the exact HTML option spelling with your version’s help output.

Minimal header document

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    body { margin: 0; font: 10px sans-serif; color: #333; }
    .header { border-bottom: 1px solid #aaa; padding: 0 0 4px; }
  </style>
</head>
<body>
  <div class="header">Quarterly report</div>
</body>
</html>

Keep the header and footer documents focused on the repeated material. Their available height depends on the page size, margins, spacing, and renderer behavior. Check a multi-page output to ensure the repeated content appears on all intended pages and does not overlap the main document.

3. Set margins and header/footer spacing

Page margins and header/footer spacing are separate controls. The top margin reserves space between the page edge and the document body; the header spacing controls the header’s distance from the content area. Set a sufficient top margin for the header’s height and spacing, and a sufficient bottom margin for the footer. Excessive header spacing can put the header outside the PDF page; the project settings reference specifically notes that increasing the top margin can correct this case. Check footer clearance in the generated PDF as well.

1. Start with margins large enough to accommodate the header and footer.
2. Adjust the header or footer spacing independently using the option supported by your installed version.
3. Render a multi-page sample and inspect the first, middle, and last pages.
4. If content overlaps the header or footer, increase the corresponding page margin. If a header is clipped beyond the page, reduce its spacing or adjust the top margin and re-render.

4. Page numbering and offsets

Header/footer numbering uses substitution sequences supported by the installed wkhtmltopdf version. Because the official settings page points to the manual for these sequences without listing all of them, do not assume a token copied from another version is universal. Check wkhtmltopdf --extended-help or your version’s manual, then render a multi-page PDF and verify the first page, last page, and any offset.

The global pageOffset setting adds a number to page numbers used in headers, footers, and the table of contents. Use it when numbering should start from a value other than the renderer’s default, and verify the resulting labels in the output.

5. Troubleshooting

Symptom	Likely cause	What to check
Header or footer does not appear	The option spelling is unsupported by this build, the HTML URL cannot be read, or settings were applied to the wrong page object.	Check local help/manual syntax, file URL and permissions, and whether the options are associated with the intended input object.
Header is clipped or missing above the page	Header spacing is too large for the available page area.	Reduce spacing or increase the top margin, then render and inspect again.
Main content overlaps the header	The top margin does not leave enough room for header height and spacing.	Increase margin.top and inspect a page with the tallest content.
Footer overlaps content or is clipped	Bottom margin or footer spacing does not fit the footer.	Adjust margin.bottom and footer spacing; inspect pages with long content and page breaks.
Page numbers show literal tokens or unexpected values	The token is unsupported, misspelled, or numbering offset differs from expectation.	Confirm substitution syntax and pageOffset behavior in the installed version’s help/manual.
HTML header has unstyled or missing assets	Relative paths resolve differently from the input document, or the process cannot access the resources.	Use resolvable asset URLs, check filesystem/network access, and confirm the resource-loading options in your build.

6. Security, reliability, and cost considerations

wkhtmltopdf renders HTML using the Qt WebKit engine. Its official downloads page warns: “Do not use wkhtmltopdf with any untrusted HTML – be sure to sanitize any user-supplied HTML/JS, otherwise it can lead to complete takeover of the server it is running on!” Treat HTML, JavaScript, and URLs supplied by users as untrusted input; apply a deliberate sanitization and isolation strategy before rendering.

The project downloads page lists 0.12.6 as the stable series and gives June 11, 2020 as its release date. That is the project’s stated release information, not a guarantee that this version is installed or suitable for every current platform. Record the executable version in deployment, keep a representative PDF fixture, and inspect output after changing the binary, fonts, input markup, or operating environment. The cited project materials provide no benchmark or cost figures for header/footer rendering, so measure resource use and runtime with your own documents and workload.

Or skip the browser setup

If your goal is a screenshot of a web page rather than a PDF rendered by wkhtmltopdf, ScreenshotNeo is a website screenshot API and MCP server. It does not add headers or footers to wkhtmltopdf output. For a screenshot, one GET request returns an image or PDF:

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com/report \
  -o shot.webp

See the ScreenshotNeo API documentation for the request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, with response headers indicating the page verdict and billing status. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for free.

FAQ

Can I use both text options and an HTML header?

The settings reference documents both positional text fields and an HTML document URL. Check your version’s CLI help for how those options interact when combined.

Will the header appear on every page?

Header/footer settings are associated with page objects, and the intended effect is repeating page furniture. Confirm the result with a multi-page PDF and the object arrangement used by your command.

Does wkhtmltopdf support every modern CSS feature in my header?

It uses Qt WebKit, so do not assume behavior matches a current browser. Keep the header layout simple and inspect rendered output in the exact deployment environment.

Where can I find the options for my installed version?

Run wkhtmltopdf --help or wkhtmltopdf --extended-help and consult the manual matching the executable. The project also publishes its settings reference.

Official references

• libwkhtmltox settings: header/footer fields, margins, page offset, and object settings.
• HeaderFooter API reference: header and footer content and layout fields.
• Official downloads: stated stable version and security warning.
• Project overview: tool purpose and rendering engine.