Use wkhtmltopdf options through pdfkit’s options dictionary. Keys omit the leading --, so --footer-center "Page [page] of [topage]" becomes "footer-center": "Page [page] of [topage]". Reserve enough top and bottom margin for the content, and verify that your wkhtmltopdf binary includes the patched-Qt features required for headers and footers.
Prerequisites and the option mapping
pdfkit is a Python wrapper around the wkhtmltopdf executable. Install both components, then confirm that Python can find the executable:
python -m pip install pdfkit
wkhtmltopdf --versionIf wkhtmltopdf is not on PATH, pass its location explicitly:
import pdfkit
config = pdfkit.configuration(wkhtmltopdf="/usr/local/bin/wkhtmltopdf")
pdfkit.from_file("report.html", "report.pdf", configuration=config)Every wkhtmltopdf switch is represented by a dictionary key without --. Values are strings unless the option is a simple boolean flag.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
| wkhtmltopdf command-line option | pdfkit key | Purpose |
|---|---|---|
--header-left |
header-left |
Plain text at the left of each page header |
--header-center |
header-center |
Centered plain-text header |
--header-right |
header-right |
Right-aligned plain-text header |
--footer-left |
footer-left |
Plain-text footer at left |
--footer-center |
footer-center |
Centered footer, commonly page numbers |
--footer-right |
footer-right |
Right-aligned footer |
--header-html |
header-html |
HTML document used as the header |
--footer-html |
footer-html |
HTML document used as the footer |
Add a plain-text header and page-number footer
This complete example converts a local HTML file and adds a report title, a right-side status label, and a centered “Page n of total” footer:
import pdfkit
options = {
"header-left": "Quarterly report",
"header-right": "Internal",
"footer-center": "Page [page] of [topage]",
"margin-top": "20mm",
"margin-bottom": "18mm",
"header-spacing": "5",
"footer-spacing": "5",
}
pdfkit.from_file("report.html", "report.pdf", options=options)The same dictionary works with the other conversion entry points:
pdfkit.from_url("https://example.com", "site.pdf", options=options)
pdfkit.from_string("<h1>Generated report</h1>", "string.pdf", options=options)[page] is replaced with the current page number and [topage] with the last page number. wkhtmltopdf also documents these substitutions:
Rank #2
[frompage]and[webpage][section]and[subsection][date],[isodate], and[time][title]and[doctitle][sitepage]and[sitepages]
Keep the token brackets exactly as shown. They are expanded by wkhtmltopdf during PDF generation, not by Python.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Make the header or footer look like part of the document
Plain-text switches are sufficient for simple labels. Use the font and line options when you need predictable basic styling:
options = {
"header-center": "Engineering handbook",
"header-font-name": "Arial",
"header-font-size": "9",
"header-line": "",
"footer-right": "Page [page] of [topage]",
"footer-font-name": "Arial",
"footer-font-size": "8",
"footer-line": "",
"margin-top": "22mm",
"margin-bottom": "18mm",
"header-spacing": "4",
"footer-spacing": "4",
}
pdfkit.from_file("handbook.html", "handbook.pdf", options=options)A line option is a flag; an empty string is a practical way to express it in a pdfkit dictionary. Test the exact syntax with your installed wrapper if a flag is ignored.
Margins and spacing are geometric settings, not decoration. The top margin must contain the header plus its spacing; the bottom margin must contain the footer plus its spacing. Excessive header spacing can move the header outside the page. Increase margin-top (or reduce spacing) when text is clipped, overlaps body content, or disappears.
Use an HTML header or footer for logos and richer layouts
For multiple elements, custom fonts, colors, or a logo, point wkhtmltopdf to an HTML document:
options = {
"header-html": "header.html",
"footer-html": "footer.html",
"margin-top": "28mm",
"margin-bottom": "24mm",
"header-spacing": "4",
"footer-spacing": "4",
}
pdfkit.from_file("report.html", "report.pdf", options=options)A minimal footer.html might be:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
body { margin: 0; font: 9pt Arial, sans-serif; color: #555; }
.footer { width: 100%; border-top: 1px solid #bbb; padding-top: 4px; }
.row { display: flex; justify-content: space-between; }
</style>
</head>
<body>
<div class="footer">
<div class="row">
<span>Confidential</span>
<span>Page [page] of [topage]</span>
</div>
</div>
</body>
</html>The HTML-header mechanism expects an HTML document location. Depending on the wkhtmltopdf and pdfkit versions, a local path, a file:// URI, or another URI form may be required. If a relative path fails, use an absolute path or the URI form accepted by your installed binary. Keep external assets reachable and use absolute paths for local images and stylesheets when necessary.
Rank #4
- Funny saying for any front-end developer, web developer, computer programmer, computer systems engineer, mobile app developer, software developer, or code lover who likes to code, make funny programming jokes, and take memorable photos.
- Wear it proudly at International Programmers' Day, school, coding classes, or coding communities! It also makes a funny present for a computer programming lover friend.
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
The header/footer page receives substitution parameters in the wkhtmltopdf HTML-header model. A script in the document can read the query parameters and insert values such as the current page. If your design depends on this, inspect the generated PDF on the target operating system because URI and JavaScript handling can vary by build.
Choose between plain text and HTML
| Need | Use | Trade-off |
|---|---|---|
| One label or page counter | header-left, footer-center, and related options |
Fastest and simplest, with limited styling |
| Logo, rules, columns, or branded typography | header-html or footer-html |
More control, but an additional document must resolve correctly |
| Dynamic page values | Tokens such as [page] and [topage] |
Expansion occurs in wkhtmltopdf, so test with the actual binary |
Check patched-Qt compatibility before debugging your code
Headers and footers are among the features that depend on wkhtmltopdf’s patched Qt build. Some Debian and Ubuntu repository packages omit patched functionality, and pdfkit’s project documentation specifically warns that such builds can lack headers, footers, outlines, and table-of-contents support.
- Run
wkhtmltopdf --versionand record the exact executable and version. - Confirm which binary pdfkit invokes; pass
pdfkit.configuration(wkhtmltopdf=...)when more than one installation exists. - Generate a tiny test PDF containing only
footer-center: Page [page] of [topage]. - If the footer is absent while the conversion otherwise succeeds, install a build that includes the required patched functionality rather than changing CSS randomly.
Availability is build- and packaging-dependent. Do not assume that two machines running a similarly named package support the same switches.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesBest Value
- Programming Language Lover Code Apparel. App or Web Design and Development Expert Funny Dress. Best Valentines Idea For Coding Lover. HTML Code or Meaning Costume
- Funny I Know HTML - How To Meet Ladies Computer Programmer Quotes
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
Reliable layout and operational practices
Reserve space deliberately
- Measure the tallest header and footer, then set margins larger than those heights.
- Increase spacing only when you need a gap; spacing that is too large can push content outside the page.
- Inspect the first, middle, and last pages for clipping and overlap.
Keep conversion inputs deterministic
- Use stable, absolute asset paths for local files.
- Wait for web fonts and JavaScript-driven content before conversion, or render a static report HTML.
- Use the same wkhtmltopdf binary in development, CI, and production.
- Save stderr and the exit status so failed conversions are distinguishable from PDFs with missing decorations.
Control runtime and output size
Headers and footers are rendered for every page, so complex HTML, large images, and remote assets increase work. Keep header/footer markup small, optimize images, and avoid unnecessary JavaScript. For large reports, convert a representative document first and check memory use and elapsed time on the deployment host; the supplied documentation does not establish a universal performance figure.
Troubleshooting common failures
| Symptom | Likely cause | Fix |
|---|---|---|
| No header or footer at all | Unsupported wkhtmltopdf build or wrong executable | Check --version, the path used by pdfkit, and install a patched-Qt build that supports the option. |
| Header overlaps the report | Top margin is smaller than header plus spacing | Increase margin-top or reduce header-spacing. |
| Footer is clipped or covers text | Insufficient bottom margin | Increase margin-bottom; inspect pages with the tallest footer. |
| Page tokens print literally | Option was passed to HTML/CSS instead of wkhtmltopdf, or the option was ignored | Put the token in footer-center or supported header/footer HTML and test the binary directly. |
| HTML header is blank | URI or local-resource resolution failed | Try an absolute path or accepted file:// URI, and verify referenced assets. |
| Works locally, fails on Linux server | Different package, fonts, permissions, or executable path | Pin the binary, install required fonts, use absolute paths, and log stderr. |
| Conversion raises an executable error | wkhtmltopdf is missing or not executable | Install it, make the path explicit with pdfkit.configuration, and rerun the version command as the service user. |
Or skip the browser setup
If your real goal is a clean image or PDF of a URL rather than a locally rendered wkhtmltopdf document, ScreenshotNeo provides a single HTTP request. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.
cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
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)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for PDF parameters, headers, cookies, custom JavaScript, waiting rules, device and viewport settings, and signed webhooks. Its MCP server lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Frequently Asked Questions
Can I put page numbers in the left or right footer?
Yes. Use the corresponding option, such as footer-right or footer-left, with Page [page] of [topage].
Why does an HTML footer work on one machine but not another?
Local-file URI handling, executable packaging, fonts, and patched-Qt support differ by environment. Compare the exact wkhtmltopdf binary and use an absolute or accepted file URI.
Does pdfkit itself render the header?
No. pdfkit forwards the dictionary options; wkhtmltopdf performs the conversion and token substitution.
The Bottom Line
Pass header and footer switches without leading dashes, reserve explicit margins, and verify that the invoked wkhtmltopdf build supports patched headers and footers. Use HTML header/footer documents when plain text is not enough.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
