ScreenshotNeo

BlogHow-to

How to Set the Footer Font in wkhtmltopdf

Set wkhtmltopdf footer fonts with built-in options or HTML/CSS, troubleshoot missing fonts, and automate reliable PDF output.

By the ScreenshotNeo team30 September 20268 min read

How to Set the Footer Font in wkhtmltopdf

Direct answer: wkhtmltopdf’s built-in text footer uses --footer-font-name for the font family and --footer-font-size for the size. The documented defaults are Arial and 12. A complete command looks like this:

wkhtmltopdf \
  --footer-center "Page [page] of [topage]" \
  --footer-font-name "DejaVu Sans" \
  --footer-font-size 10 \
  input.html output.pdf

Use a font that is installed and available to the machine running wkhtmltopdf. If your footer is supplied with --footer-html, set the font in that HTML document’s CSS instead. The official usage reference documents these options, their defaults, footer positions, page variables, and build requirements: wkhtmltopdf usage documentation.

wkhtmltopdf has two different footer mechanisms. The right font setting depends on which one you use:

Choose built-in footer flags for simple text or an HTML footer for CSS layout.
Choose built-in footer flags for simple text or an HTML footer for CSS layout.
Footer type How you enable it How you set the font Best for
Built-in text --footer-left, --footer-center, or --footer-right --footer-font-name and --footer-font-size Simple labels, dates, and page numbers
HTML footer --footer-html footer.html CSS font-family and font-size inside the footer document Branding, multiple lines, rules, images, and custom layout

Changing a header option does not change the footer. Header settings have their own names, including --header-font-name and --header-font-size.

Built-in footers are created by placing text on the left, center, or right. Page variables such as [page] and [topage] are expanded when the PDF is rendered.

wkhtmltopdf \
  --footer-left "Acme Engineering" \
  --footer-center "Page [page] of [topage]" \
  --footer-right "Internal" \
  --footer-font-name "DejaVu Sans" \
  --footer-font-size 9 \
  report.html report.pdf

The option values are separate arguments, so quote font names containing spaces. For example, use "Liberation Sans", not two unquoted arguments. The size is a number understood by the executable; keep it consistent across environments when comparing output.

Minimal examples

# Centered footer using the documented default family and size
wkhtmltopdf --footer-center "Page [page] of [topage]" input.html output.pdf

# Explicit Arial at 12
wkhtmltopdf \
  --footer-center "Page [page] of [topage]" \
  --footer-font-name "Arial" \
  --footer-font-size 12 \
  input.html output.pdf

# Smaller footer with a font installed on the host
wkhtmltopdf \
  --footer-center "Page [page] of [topage]" \
  --footer-font-name "Liberation Sans" \
  --footer-font-size 9 \
  input.html output.pdf

The first command relies on the documented defaults. Being explicit is usually easier to audit in a build script, especially when different Linux, macOS, and Windows machines have different installed fonts.

Use --footer-html when the footer needs custom markup. Put the font declaration on an element that contains the footer content:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <style>
    html, body {
      margin: 0;
      padding: 0;
      font-family: "DejaVu Sans", Arial, sans-serif;
      font-size: 9pt;
      color: #555;
    }
    .footer {
      width: 100%;
      text-align: center;
    }
  </style>
</head>
<body>
  <div class="footer">Page <span class="page"></span> of <span class="topage"></span></div>
</body>
</html>

Render it with:

wkhtmltopdf \
  --footer-html footer.html \
  --margin-bottom 20mm \
  report.html report.pdf

An HTML footer is an ordinary HTML/CSS document from a styling perspective. The usage documentation confirms that --footer-html supplies an HTML footer, but exact CSS precedence and rendering details can vary by installed build. Verify typography with the executable you deploy.

wkhtmltopdf builds commonly expose page variables to the footer document. Depending on the build and template, these are often represented with elements or scripts documented by that build. Check the output of wkhtmltopdf --help and the project documentation for your version before depending on a particular template. If page numbering is the only requirement, the built-in --footer-center "Page [page] of [topage]" form is simpler.

4. Make sure the font exists in the rendering environment

A font name is not an installation step. wkhtmltopdf can only use fonts visible to the operating system and user account that runs it. A developer workstation may have a font that is absent in a container, CI runner, server, or worker process.

The rendering host must have the requested font installed and accessible.
The rendering host must have the requested font installed and accessible.

Linux checks

# List matching families
fc-match "DejaVu Sans"
fc-match Arial

# Search the font database
fc-list | grep -i "Liberation Sans"

# Refresh the cache after installing fonts
fc-cache -f -v

Install fonts through your distribution’s supported package mechanism or include the font files in the image you deploy. Keep licensing requirements in mind for commercial fonts. Use a generic fallback in HTML, for example font-family: "Brand Font", Arial, sans-serif, but remember that fallback changes glyph metrics and line wrapping.

Windows and macOS checks

Confirm that the font is installed for the account running the process. Services can run under a different account from the interactive desktop user. A font visible in a GUI application is not proof that a scheduled task or service can access it.

Fonts affect width, height, and baseline position. A larger footer can overlap body content if the bottom margin is too small. Increase --margin-bottom when you increase the font size or use multiple lines.

wkhtmltopdf \
  --footer-center "Page [page] of [topage]" \
  --footer-font-name "DejaVu Sans" \
  --footer-font-size 11 \
  --margin-bottom 24mm \
  input.html output.pdf

For an HTML footer, set the document’s height and the PDF bottom margin together. Render a page with long titles, wide numbers, and the highest page count you expect; these cases expose clipping and wrapping problems.

6. Option placement and configuration reference

Option Purpose Notes
--footer-left <text> Left aligned built-in footer text Supports replacement variables documented by the build
--footer-center <text> Centered built-in footer text Common choice for page numbering
--footer-right <text> Right aligned built-in footer text Useful for dates or document identifiers
--footer-font-name <name> Built-in footer family Documented default: Arial
--footer-font-size <size> Built-in footer size Documented default: 12
--footer-html <url> HTML footer document Style its content with CSS
--margin-bottom <unit> Space below the body Increase it when the footer is tall

Keep global options before the input and output arguments. In a shell script, quote every value that contains spaces or shell metacharacters.

“Unknown long argument” or an ignored option

Cause: the installed executable may be an older or differently packaged build. The usage material marks some footer features as requiring patched Qt, and packaged builds can differ.

Fix: run wkhtmltopdf --version and inspect wkhtmltopdf --help from the same path your application invokes. Do not assume a globally installed binary is the one used by a service. If the option is absent, use a compatible build or move the footer into an HTML document and style it with CSS.

Cause: you may be using --footer-html, where the built-in font option does not style the HTML document, or the requested font is unavailable and a fallback is being selected.

Fix: add font-family to the HTML footer CSS, then verify the family with fc-match (Linux) or the service account’s installed fonts. Confirm that the command actually contains the option you intended.

The text is clipped or overlaps the page

Cause: the footer’s rendered height exceeds the reserved bottom margin.

Fix: increase --margin-bottom, reduce the font size, shorten the text, or reduce the HTML footer’s line height. Test with the longest expected footer.

The chosen font changes between environments

Cause: font availability and fallback order differ across hosts.

Fix: package the same font set with each runtime, specify an explicit fallback stack, and record the wkhtmltopdf version in deployment metadata. Compare PDFs generated by the actual production executable.

Page variables appear literally

Cause: the variable syntax may not be supported in the footer type or build you are using.

Fix: try the documented built-in text form, such as --footer-center "Page [page] of [topage]". For HTML footers, follow the variable mechanism supported by your installed version and inspect its help output.

Cause: the footer option was omitted, the HTML footer path is wrong, or the footer is outside the printable area.

Fix: start with a centered built-in footer, use an absolute or verified path for --footer-html, and increase the bottom margin. Capture stderr from the command so file and resource errors are visible.

8. Automate wkhtmltopdf safely

Use a small wrapper so every job receives the same font and margin settings. Check exit status and preserve stderr for diagnosis.

#!/usr/bin/env bash
set -euo pipefail

input="$1"
output="$2"

wkhtmltopdf \
  --footer-center 'Page [page] of [topage]' \
  --footer-font-name 'DejaVu Sans' \
  --footer-font-size 9 \
  --margin-bottom 18mm \
  "$input" "$output"

For repeatable output, pin the wkhtmltopdf package or container image, install the same fonts, and keep input HTML deterministic. Avoid changing a font family without reviewing page breaks: different glyph widths can move content to another page and change [topage].

9. Performance, reliability, and cost considerations

Font selection usually has a smaller cost than rendering the source page, but HTML footers can add document loading, CSS parsing, and image work. Keep the footer self-contained and lightweight. A local footer file avoids dependence on a remote URL and makes failures easier to reproduce.

For reliability, validate the executable and fonts at startup, log the exact command or structured options, and render a representative fixture in CI. Include a long document, a one-page document, a large page number, and non-ASCII characters if your footer uses them. Do not infer that a successful process exit guarantees the intended font was used; inspect the resulting PDF when typography is a requirement.

wkhtmltopdf is a local command-line renderer, so its direct cost is the compute and storage of your own environment. If you need website screenshots rather than PDFs, a managed capture API can remove browser and font setup work.

10. Or skip the browser setup

For a website screenshot or PDF capture workflow, ScreenshotNeo provides one GET request and handles the capture service. Read the API documentation for the complete option set.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing result. ScreenshotNeo also has an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.

The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.

11. FAQ

The documented default is Arial at size 12 for the built-in text footer.

No. Use CSS in the document passed to --footer-html.

The built-in footer needs a font available to the rendering environment. For predictable output, install and verify the font locally rather than relying on a remote web font.

Headers and footers have separate option families. Use --footer-font-name and --footer-font-size for built-in footer text.

How do I know which wkhtmltopdf build I have?

Run wkhtmltopdf --version and inspect that executable’s --help. Feature support, including patched-Qt-only options, can vary by package.