Configure wkhtmltopdf defaults at the layer that owns them: put document-wide command-line options before any page objects, put page options after the specific input they should affect, or set named values through the separate libwkhtmltox global and object settings APIs. There is no single, universal wkhtmltopdf configuration file established by the command-line manual, and wrapper packages can supply defaults that differ from the binary.
Start by checking the executable you will actually run with wkhtmltopdf --version, wkhtmltopdf --help, and, when needed, wkhtmltopdf --extended-help. The installed build is authoritative because distribution packages and downstream builds can vary.
How wkhtmltopdf decides which setting to use
wkhtmltopdf has two command-line scopes:
- Global options apply to the document conversion or to page objects generally. They must appear before the first input/object.
- Page (object) options control a particular URL or input document. They can be supplied in the global area for broad application, or after an individual object to scope them to that object.
The official usage manual summarizes this behavior as: “options can be specified on a per object basis or in the global options area.” See the wkhtmltopdf usage manual for the option classification in your version.
For a conversion containing several pages, wkhtmltopdf parses the command from left to right. An option placed after one input does not retroactively change an earlier object. Conversely, placing a setting before all inputs makes it part of the global configuration for the conversion.
#1 Best Overall
![PDF Extra 2024| Complete PDF Reader and Editor | Create, Edit, Convert, Combine, Comment, Fill & Sign PDFs | Lifetime License | 1 Windows PC | 1 User [PC Online code]](https://m.media-amazon.com/images/I/41eZq4aiipL._SL160_.jpg)
- EDIT text, images & designs in PDF documents. ORGANIZE PDFs. Convert PDFs to Word, Excel & ePub.
- READ and Comment PDFs – Intuitive reading modes & document commenting and mark up.
- CREATE, COMBINE, SCAN and COMPRESS PDFs
- FILL forms & Digitally Sign PDFs. PROTECT and Encrypt PDFs
- LIFETIME License for 1 Windows PC or Laptop. 5GB MobiDrive Cloud Storage Included.
Check the binary before changing anything
- Run
wkhtmltopdf --versionand record the output in your build log or deployment notes. - Run
wkhtmltopdf --helpto see normal options. Use--extended-helpfor less common switches and their descriptions. - Compare the option names and defaults shown by that executable with any documentation for your operating-system package. Do not assume that a value listed for one release is guaranteed in another.
- Convert a representative page, then inspect the PDF’s paper size, orientation, margins, images, links, headers, and footers. Treat this as a verification step after every meaningful default change.
The examples below use option names documented by the 0.12.6 usage text. They illustrate scope and intent; your local help output remains the final authority.
Representative command-line defaults in the 0.12.6 manual
The 0.12.6 usage manual lists the following examples. They are documented values, not an exhaustive list and not a promise that every package build uses them.
| Setting | Documented default | What it affects |
|---|---|---|
| Paper size | A4 | Default PDF page dimensions |
| Orientation | Portrait | Page orientation unless changed to landscape |
| DPI | 96 | Documented rendering DPI option |
| Copies | 1 | Number of output copies |
| Image DPI downscaling | 600 | Threshold used by the image downscaling option |
| JPEG quality | 94 | Quality value for JPEG output or conversion |
| Outline | Enabled | Whether an outline is generated when supported by the document |
| Background printing | Enabled | Whether CSS backgrounds are printed |
These values belong to the manual’s documented version. A wrapper, patched build, or newer package may change behavior, add defaults, or omit an option. If exact reproducibility matters, pin the executable and capture its version and help output alongside your application.
Set document-wide defaults on the command line
A basic global configuration
Place global options before the URL and output filename:
wkhtmltopdf
--page-size A4
--orientation Portrait
--margin-top 18mm
--margin-right 18mm
--margin-bottom 18mm
--margin-left 18mm
--dpi 96
--background
https://example.com report.pdfHere, page size, orientation, margins, DPI, and background printing are global for the conversion. Explicitly writing a value that matches the documented default can still be useful: it makes the intended policy visible in source control and protects the calling script if a package default changes.
Global loading and rendering behavior
Options such as encoding, JavaScript execution, load delays, custom headers, cookies, and user-agent strings are page/object settings in the command-line model. Supplying one before the first URL makes it the default for the page objects in that invocation:
wkhtmltopdf
--encoding utf-8
--javascript-delay 800
--custom-header "X-Render-Mode" "pdf"
https://example.com invoice.pdfUse only options shown by your installed binary. Some builds disable features or expose additional switches, so copying a command from another host can produce an “Unknown long argument” error.
Rank #2
- Edit PDFs with Ease. Modify text, images, and layouts directly within your PDF documents.
- Convert & Organize. Export PDFs to Word, Excel, or ePub, and organize files with ease.
- Read & Annotate. Enjoy intuitive reading modes and powerful tools to comment, highlight, and mark up PDFs.
- Create & Manage PDFs. Create new PDFs, combine multiple files, scan documents, and compress for easy sharing.
- Fill & Sign Forms. Complete forms and digitally sign documents with secure e-signature tools.
Scope a setting to one page object
When converting multiple inputs, put an object-specific option after the input it belongs to and before the next object:
Recommended Free Tools
wkhtmltopdf
--page-size A4
https://example.com/summary
--zoom 1.15
--header-center "Summary"
https://example.com/details
--zoom 0.95
--header-center "Details"
combined.pdfThe global paper size applies to both objects. The zoom and header values are attached to their respective page objects. If you instead put --zoom 1.15 before the first URL, it becomes the broad setting for the conversion.
When a page option should be global
Use the global area when every page needs the same encoding, cookie, delay, viewport-related behavior, header, or footer. This avoids subtle differences caused by repeating options inconsistently.
When to keep it per object
Keep a setting after an input when pages have different languages, authentication cookies, zoom levels, headers, or JavaScript timing. Per-object placement also makes a mixed conversion self-documenting.
Record defaults in a script instead of relying on an invisible machine state
The reviewed command-line documentation describes options passed to each invocation; it does not establish a universal persistent configuration file. For repeatable builds, store the complete argument list in your shell script, task runner, container image, or application configuration and invoke that single definition everywhere.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →#!/usr/bin/env bash
set -euo pipefail
WKHTMLTOPDF_BIN="${WKHTMLTOPDF_BIN:-wkhtmltopdf}"
COMMON_ARGS=(
--page-size A4
--orientation Portrait
--margin-top 18mm
--margin-right 18mm
--margin-bottom 18mm
--margin-left 18mm
--encoding utf-8
--background
)
"$WKHTMLTOPDF_BIN" "${COMMON_ARGS[@]}" "$1" "$2"Keep the executable path configurable so a CI job can use the same pinned binary as production. Log the version once per run, and fail fast if a required option is not accepted by that build.
Configure defaults through libwkhtmltox
Applications embedding wkhtmltopdf use libwkhtmltox rather than constructing a shell command. The C interface exposes separate global and object settings. Create the appropriate settings object, set a named UTF-8 value, check the setter’s success result, then create a converter with the configured global settings.
Rank #3
- Create and edit PDFs. Collaborate with ease. E-sign documents and collect signatures. Get everything done in one app, wherever you go.
- Edit text and images without jumping to another app.
- E-sign documents or request e-signatures on any device. Recipients don’t need to log in to e-sign.
- Convert PDFs to editable Microsoft Word, Excel, or PowerPoint documents.
- Share PDFs for collaboration. Commenting features make it easy for reviewers to comment, mark up, and annotate.
#include <wkhtmltox/pdf.h>
#include <stdio.h>
int main(void) {
wkhtmltopdf_global_settings *global =
wkhtmltopdf_create_global_settings();
wkhtmltopdf_object_settings *object =
wkhtmltopdf_create_object_settings();
if (!global || !object) return 1;
if (!wkhtmltopdf_set_global_setting(global, "size.pageSize", "A4")) {
fprintf(stderr, "Could not set global paper sizen");
return 1;
}
if (!wkhtmltopdf_set_global_setting(global, "orientation", "Portrait")) {
fprintf(stderr, "Could not set global orientationn");
return 1;
}
if (!wkhtmltopdf_set_object_setting(object, "web.defaultEncoding", "utf-8")) {
fprintf(stderr, "Could not set object encodingn");
return 1;
}
wkhtmltopdf_converter *converter =
wkhtmltopdf_create_converter(global);
if (!converter) return 1;
/* Add the object, run the converter, and inspect converter status. */
wkhtmltopdf_add_object(converter, object, NULL);
/* wkhtmltopdf_convert(converter); */
/* wkhtmltopdf_destroy_converter(converter); */
return 0;
}Names such as size.pageSize and web.defaultEncoding are API setting names, not command-line spellings. Use the settings API documentation shipped with your library version, retrieve values when diagnosing a configuration, and do not ignore a false return from a setter. Global settings belong to the global settings instance; rendering, loading, and page behavior belong to the object settings instance.
Do not confuse binary defaults with wrapper defaults
A framework integration can add its own option dictionary and defaults before it calls wkhtmltopdf. The django-wkhtmltopdf 3.2.0 settings documentation, for example, lists wrapper defaults of encoding=utf8 and quiet=True. Those values describe that wrapper’s behavior; they do not prove that the standalone wkhtmltopdf binary has the same defaults.
A practical precedence check
- Inspect the framework setting or constructor that your application uses.
- Inspect the wrapper’s generated command or API calls, if it exposes them in debug mode.
- Check the actual wkhtmltopdf binary with
--versionand--help. - Resolve conflicts explicitly in the highest layer you control, then record the resulting value in application configuration.
If a wrapper exposes a persistent settings dictionary, use that documented mechanism rather than editing an assumed system-wide file. Keep wrapper configuration and binary configuration documented separately.
Common failures and fixes
“Unknown long argument”
Cause: the option is absent, renamed, disabled, or placed where that build does not accept it.
Fix: run wkhtmltopdf --extended-help on the same executable used by the job, remove unsupported switches, and verify that a wrapper is not targeting a different binary.
The option changes every page instead of one
Cause: it was placed in the global options area before the first object.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchFix: move the option after the specific input URL and before the next object. Check the final argument order in the process log.
Rank #4
- Perfect Adobe Acrobat Pro alternative – lifetime license for Windows 10 and 11.
- EDIT text, images, pages, hyperlinks, designs in PDF documents. ORGANIZE PDFs.
- READ and Comment on PDFs – Intuitive reading modes & document commenting and mark up tools!
- CREATE, COMBINE, SCAN and COMPRESS PDFs.
- FILL forms & Digitally Sign PDFs. Work with Digital certificates
The option appears to do nothing
Cause: a later object setting, wrapper value, CSS rule, or package patch overrides it; some options also require a compatible document or output mode.
Fix: reduce the command to one URL, print the effective wrapper arguments, and test the option in isolation. Confirm the output property you are measuring rather than relying only on a quiet exit status.
Different hosts produce different PDFs
Cause: different wkhtmltopdf builds, fonts, WebKit behavior, locales, or wrapper defaults.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Fix: pin the executable, install the same fonts, record --version output, and keep the complete argument list in source control. Treat the 0.12.6 manual’s values as version-specific documentation, not a cross-distribution contract.
Images or CSS backgrounds are missing
Cause: the page needs background printing, resources have not finished loading, or the target requires JavaScript.
Fix: verify --background, use an appropriate page delay or wait strategy supported by your build, and inspect the page directly for resource or authentication failures. Do not increase delays blindly; measure the slowest representative pages.
The process hangs or times out
Cause: a page never finishes loading, JavaScript keeps the event loop active, or an external resource is unreachable.
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
- ALL-IN-ONE SOLUTION – read, edit, convert, merge and protect your PDF files
- MAXIMUM FUNCIONALITY – create interactive forms, compare PDFs, bates numbering, find and replace text or colors, convert documents, OCR engine, comment, highlight, fill out and print forms, document protection and others
- EASY TO INSTALL AND USE – well-structured user-interface, in-program instructions, free tech support whenever you need it
- GREAT VALUE FOR MONEY - why spend a fortune if you can have maximum functionality at a reasonable price - this also fits the requirements of companies very well
Fix: reproduce with one URL, add a bounded load strategy supported by the executable, check DNS and outbound access, and terminate the process from the calling application after its own deadline. Capture stderr while troubleshooting instead of using --quiet.
Performance, reliability, and maintenance choices
- Use one stable argument profile: fewer per-page differences make cache keys, regression comparisons, and incident diagnosis clearer.
- Separate document policy from content: keep paper size, margins, fonts, and security-related headers in configuration; pass URLs and page-specific values as data.
- Bound waits: a delay that fixes one JavaScript-heavy page can slow every page when applied globally. Prefer the smallest global value and override only exceptional objects.
- Preserve diagnostics: write stderr and the exact executable version to build logs. Enable quiet mode only after the conversion path is stable.
- Verify after upgrades: package maintainers can change defaults or patches even when your command line is unchanged. Re-run representative conversions and compare page geometry, links, images, and text extraction.
Or skip the browser setup
If your actual requirement is a clean screenshot or PDF of a public URL rather than controlling a wkhtmltopdf binary, ScreenshotNeo provides a single HTTP request. Its capture service accepts the cookie or consent banner before the shot and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.
See the ScreenshotNeo API documentation for all options, including full-page lazy-image loading, CSS-selector element capture, dark mode, device presets, custom viewport and retina scale, PDF paper and margin controls, custom CSS or JavaScript, click-before-capture, selector waits, network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, TTL caching, signed image links, asynchronous webhooks, bulk capture, usage data, and the OpenAPI specification.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
r.raise_for_status()
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}`);ScreenshotNeo also includes 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 shots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently Asked Questions
How can I tell whether a value came from wkhtmltopdf or my framework?
Run the standalone executable with --version and inspect the wrapper’s generated arguments separately. A value documented by a wrapper, such as django-wkhtmltopdf 3.2.0’s quiet=True, belongs to that wrapper unless the binary documentation independently lists it.
Can I apply different paper sizes in one command?
Keep document-wide settings in the global area and test whether your installed build supports the required per-object page option. If it does not, create separate conversions; the command-line model does not make every global setting object-specific.
What should an application do when a libwkhtmltox setter fails?
Treat a false setter result as a configuration error, report the setting name and value, and stop or apply a documented fallback. Continuing silently can produce a PDF with an unintended default.
The Bottom Line
For wkhtmltopdf, “default settings” are layer- and version-dependent: verify the binary, place global options before objects, scope page options after the relevant input, and keep wrapper or libwkhtmltox settings documented separately.
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.
