How to Hide the wkhtmltopdf Header on the First Page
wkhtmltopdf has no documented switch to hide a header only on page one. Use a headerless cover when it fits, or cautiously test a custom HTML header.

Short answer: wkhtmltopdf 0.12.6 with patched Qt does not document a switch that hides a header only on the first page of a regular page object. If your first page can be its own document object, use a cover: the manual says covers have no headers or footers. Otherwise, a custom HTML header can attempt to hide its content when the substituted page number is 1, but this is a historical community suggestion, not a confirmed cross-version recipe. Render and inspect the PDF produced by your exact binary.
This distinction matters: --header-spacing adjusts the gap between a header and content; it does not suppress the header on a particular page. The examples below use the documented object model and header options in the 0.12.6 manual. Check your installed version and Qt build before relying on behavior.
1. Check your wkhtmltopdf build
First identify the executable and version that actually creates the PDF. A wrapper, container, or deployment host may use a different binary from your development machine.
wkhtmltopdf --version
wkhtmltopdf --extended-help
The cited usage manual identifies itself as wkhtmltopdf 0.12.6 (with patched qt). Record the output and the environment alongside any header workaround. The manual’s options are not a guarantee that every package or wrapper exposes identical capabilities.
2. Choose a layout that matches the document
| Approach | Use it when | Important limitation |
|---|---|---|
Separate cover object |
The first page is a distinct cover or landing page. | A cover is a document-structure choice; it is not a conditional header setting for an ordinary page. |
Custom --header-html |
The header can be controlled as HTML and you can validate the generated PDF. | The page-number JavaScript approach comes from a user issue and is not confirmed across versions or builds. |
| Text header options | You need a simple repeated text header such as a title or label. | The documented text options do not provide a first-page exclusion switch. |
If the first page must remain part of one ordinary HTML page object and the header is a text option such as --header-left, the cited manual does not establish a reliable way to omit it from page one. Consider changing the document structure, or use a rendering workflow whose header behavior you can control and validate.
3. Use a headerless cover object
A cover object contains a single webpage and does not have headers or footers. It is useful for a title page, report cover, or other first page that can be authored independently. The rest of the document can be a normal page object with its repeating header.

Create two local HTML files. For example, cover.html holds the cover content and report.html holds the main report. Then pass them as separate objects:
wkhtmltopdf cover cover.html page report.html report.pdf
Object names such as cover and page tell wkhtmltopdf how to treat the following input. Add the page header options to the page object, after its object type and before its input:
wkhtmltopdf cover cover.html page \
--header-left "Quarterly report" \
--header-spacing 4 \
report.html report.pdf
Here the cover remains headerless, while the report page object receives the text header. Use a local test document with at least two pages so you can check both the transition from cover to report and the repeated header on subsequent report pages.
When this approach does not fit
- If the first page is simply page one of a long continuous HTML document, splitting it into a cover changes the document structure and potentially pagination.
- The cover object is excluded from the table of contents according to the manual. If you need the first page represented in a table of contents, account for that behavior in your document design.
- Do not expect a cover object to selectively suppress only the header while preserving all the semantics of an ordinary page object.
4. Attempt conditional hiding with a custom HTML header
A historical issue in the archived wkhtmltopdf project shows a user attempting to make a custom HTML header inspect the substituted page number and hide the header element on page 1. Treat this as an experiment: the issue is not a maintainer-confirmed recipe, and the source does not prove that the code works across versions.

Save a header template as header.html. The basic shape is:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<style>
body { margin: 0; font: 10px sans-serif; }
#running-header { padding: 4px 0; }
.hidden { display: none; }
</style>
</head>
<body>
<div id="running-header">Quarterly report</div>
<script>
// wkhtmltopdf header substitution may replace [page] in this template.
// Verify the actual value and behavior in your installed build.
var pageValue = "[page]";
if (pageValue === "1") {
document.getElementById("running-header").className = "hidden";
}
</script>
</body>
</html>
Render a multi-page input with the custom header:
wkhtmltopdf \
--header-html header.html \
--header-spacing 4 \
report.html report.pdf
The placeholder in a custom header and the timing of JavaScript execution are the uncertain parts. If the generated output displays the literal [page], runs the script before substitution, or renders the header on page one, this method has not worked in that build. Do not infer success from a clean command exit; inspect the first page and at least one later page of the output.
Validation checklist
- Run the command using the same executable, arguments, and environment used in production.
- Open the PDF and confirm page one has no visible header.
- Confirm page two and later pages still show the intended header.
- Check that the header area does not leave an unwanted blank band on page one.
- Repeat after changing the binary, Qt build, wrapper, or deployment image.
5. Keep header layout options in perspective
The manual documents several ways to define ordinary headers and footers. They configure content and position; they do not add a documented page-one condition.
| Option or feature | Purpose | Does it hide page one? |
|---|---|---|
--header-html |
Use an HTML file as header content. | No documented first-page switch; conditional HTML/JavaScript is an unverified workaround. |
--header-left and related text placements |
Place simple text in header positions. | No. |
--header-spacing |
Set spacing between header and content in millimeters. | No. Spacing changes layout, not which pages receive a header. |
Substitution variables such as [page] |
Insert page-related values in header content. | They can inform a custom-header attempt, but the manual does not document them as a conditional visibility feature. |
When diagnosing a header that appears too low or overlaps the document, adjust header spacing and page margins as separate layout concerns. Do not use a large spacing value as a substitute for suppressing the header: it can move content without removing the header itself.
6. Troubleshooting
| Symptom | Likely cause | What to try |
|---|---|---|
| The header is still visible on page one. | A regular page object has a repeated header, or the custom-header condition did not run as expected. | Use a separate cover if the layout permits. Otherwise inspect the custom header’s substituted value and output PDF; the workaround is not guaranteed. |
The literal [page] appears in the header. |
The build did not substitute the value in that template, or the substitution mechanism differs. | Confirm the version/build and test a minimal header. Do not treat the placeholder string as proof that the page condition works. |
| The first page has a blank strip at the top. | Header space or page margins may still be reserved even if the header content is hidden. | Inspect the page geometry and adjust margins or spacing for the chosen object structure. Validate that later-page content remains correctly positioned. |
| The cover is missing from the table of contents. | The manual describes cover objects as excluded from the table of contents. | Decide whether a separate cover suits the document’s navigation needs; the cover behavior is part of this workaround. |
| It works locally but not in deployment. | The server may use a different wkhtmltopdf version, Qt build, wrapper, or invocation. | Capture wkhtmltopdf --version in both environments and compare the actual command and generated PDFs. |
| Changing spacing does not remove the header. | --header-spacing controls the gap, not visibility by page. |
Choose a cover object or validate a custom HTML header attempt instead. |
7. Reliability, performance, and operational notes
This is principally a layout and build-compatibility issue. The cited sources provide no benchmark or reliability figures for either workaround, so measure your own document generation path if runtime matters. A separate cover adds an object to the document structure; its practical effect depends on the inputs and environment. The conditional header approach adds script and substitution behavior that should be treated as build-sensitive.
For reliable output, keep a small representative PDF fixture and inspect page one and a later page whenever the wkhtmltopdf executable or build changes. Automate PDF generation in the same environment as production. If your pipeline handles user-provided HTML, also define its own resource and execution constraints; the cited manual excerpt does not establish safe defaults for arbitrary input.
Cost depends on your own rendering infrastructure; the source material gives no wkhtmltopdf pricing or performance data. When comparing operational cost, include the time needed to maintain the binary, templates, and validation process rather than assuming a particular speed or infrastructure bill.
8. Or skip the browser setup
If the job is capturing a website as an image or PDF rather than rendering a local wkhtmltopdf document, ScreenshotNeo provides a website screenshot API and MCP server. One GET request can return a screenshot or PDF. See the API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webp
Python:
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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));
Cookie banners are accepted and removed before the shot, along with known newsletter popups and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. The MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The Free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots.
Create a free ScreenshotNeo account for 1,000 screenshots a month, with no card required.
9. FAQ
Can I hide a text header on page one with a command-line flag?
The cited 0.12.6 manual does not document a dedicated first-page-only header flag for an ordinary page object.
Does a cover object count as the first page of the regular page object?
It is a separate document object with its own behavior. The manual says a cover has no headers or footers and is omitted from the table of contents.
Is the JavaScript header trick officially supported?
The available example is a user contribution in a historical issue, not a maintainer-confirmed, cross-version guarantee. Validate it with your own binary and output.
Will reducing header spacing make the first-page header disappear?
No. Spacing controls the gap between header and content; it does not conditionally disable the header.
Sources
- wkhtmltopdf usage manual (0.12.6 with patched Qt), for object types, cover behavior, header options, spacing, and substitution variables.
- Historical project issue about hiding or removing the first-page header, a user example rather than confirmed support.


