WKHTMLTOPDF(1)

WKHTMLTOPDF(1) 💖

okay bestie, so this is the General Commands Manual page for wkhtmltopdf — yes, the little html-to-pdf converter that could. grab a boba, we're going in 🧋✨

---

NAME 🎀

wkhtmltopdf — html to pdf converter. that's it. that's the whole name section. iconic brevity honestly 💅

---

SYNOPSIS ✨

wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>

like, give it your global options, give it your objects, tell it where the output file goes, and it will serve. periodt.

---

DOCUMENT OBJECTS 🦋

so here's the tea: wkhtmltopdf can put several objects into the output file. an object is either:

• a single webpage 🌐
• a cover webpage 📔
• a table of contents 📑

they land in the output document in the order you specify them on the command line. options can be set per object or in the global options area. but heads up — options from the Global Options section can only live in the global options area, no exceptions bestie.

A page object 🌸

puts the content of a single webpage into the output document.

(page)? <input url/file name> [PAGE OPTION]...

options for the page object can go in the global options area and the page options area. which ones apply? check the Page Options and Headers And Footer Options sections, babes.

A cover object 📔

also puts the content of a single webpage into the output document, but the page does not appear in the table of contents, and it has no headers and footers. it's the mysterious one. main character who doesn't show up in the credits.

cover <input url/file name> [PAGE OPTION]...

every option you can set for a page object? you can set it for a cover too. slay.

A table of contents object 📑

inserts a table of contents into the output document.

toc [TOC OPTION]...

all the page-object options work here too, plus the extra ones from the TOC Options section. and the table of contents is generated via XSLT, which means you can style it to look however you want it to look. literally whatever vibe you're going for. 🎨

to get an idea of how to do this, you can dump the default xslt document by supplying --dump-default-toc-xsl, and the outline it works on by supplying --dump-outline — see the Outline Options section. iykyk 💅

---

DESCRIPTION 💖

Converts one or more HTML pages into a PDF document, not using wkhtmltopdf patched qt. (remember that. it matters later, fr fr.)

---

GLOBAL OPTIONS ✨

these are the big-picture ones, bestie. they go in the global options area only!

• --collate — Collate when printing multiple copies
• --no-collate — Do not collate when printing multiple copies
• --cookie-jar <path> — Read and write cookies from and to the supplied cookie jar file
• --copies <number> — Number of copies to print into the pdf file
• -d, --dpi <dpi> — Change the dpi explicitly (this has no effect on X11 based systems)
• -H, --extended-help — Display more extensive help, detailing less common command switches
• -g, --grayscale — PDF will be generated in grayscale
• -h, --help — Display help
• --htmldoc — Output program html help
• --license — Output license information and exit
• --log-level <level> — Set log level to: none, error, warn or info
• -l, --lowquality — Generates lower quality pdf/ps. Useful to shrink the result document space
• --manpage — Output program man page
• -B, --margin-bottom <unitreal> — Set the page bottom margin
• -L, --margin-left <unitreal> — Set the page left margin
• -R, --margin-right <unitreal> — Set the page right margin
• -T, --margin-top <unitreal> — Set the page top margin
• -O, --orientation <orientation> — Set orientation to Landscape or Portrait
• --page-height <unitreal> — Page height
• -s, --page-size <Size> — Set paper size to: A4, Letter, etc.
• --page-width <unitreal> — Page width
• -q, --quiet — Be less verbose, maintained for backwards compatibility; Same as using --log-level none
• --read-args-from-stdin — Read command line arguments from stdin
• --readme — Output program readme
• --title <text> — The title of the generated pdf file (The title of the first document is used if not specified)
• -V, --version — Output version information and exit

---

PAGE OPTIONS 🦋

these can live in the global options area or the page options area. flexible queens only. 👑

• --allow <path> — Allow the file or files from the specified folder to be loaded (repeatable)
• --background — Do print background
• --no-background — Do not print background
• --bypass-proxy-for <value> — Bypass proxy for host (repeatable)
• --cache-dir <path> — Web cache directory
• --checkbox-checked-svg <path> — Use this SVG file when rendering checked checkboxes
• --checkbox-svg <path> — Use this SVG file when rendering unchecked checkboxes
• --cookie <name> <value> — Set an additional cookie (repeatable), value should be url encoded.
• --custom-header <name> <value> — Set an additional HTTP header (repeatable)
• --custom-header-propagation — Add HTTP headers specified by --custom-header for each resource request.
• --no-custom-header-propagation — Do not add HTTP headers specified by --custom-header for each resource request.
• --debug-javascript — Show javascript debugging output
• --no-debug-javascript — Do not show javascript debugging output
• --encoding <encoding> — Set the default text encoding, for input
• --images — Do load or print images
• --no-images — Do not load or print images
• -n, --disable-javascript — Do not allow web pages to run javascript
• --enable-javascript — Do allow web pages to run javascript
• --javascript-delay <msec> — Wait some milliseconds for javascript finish
• --load-error-handling <handler> — Specify how to handle pages that fail to load: abort, ignore or skip
• --load-media-error-handling <handler> — Specify how to handle media files that fail to load: abort, ignore or skip
• --disable-local-file-access — Do not allowed conversion of a local file to read in other local files, unless explicitly allowed with --allow
• --enable-local-file-access — Allowed conversion of a local file to read in other local files.
• --minimum-font-size <int> — Minimum font size
• --page-offset <offset> — Set the starting page number
• --password <password> — HTTP Authentication password
• --disable-plugins — Disable installed plugins
• --enable-plugins — Enable installed plugins (plugins will likely not work)
• --post <name> <value> — Add an additional post field (repeatable)
• --post-file <name> <path> — Post an additional file (repeatable)
• -p, --proxy <proxy> — Use a proxy
• --proxy-hostname-lookup — Use the proxy for resolving hostnames
• --radiobutton-checked-svg <path> — Use this SVG file when rendering checked radiobuttons
• --radiobutton-svg <path> — Use this SVG file when rendering unchecked radiobuttons
• --run-script <js> — Run this additional javascript after the page is done loading (repeatable)
• --ssl-crt-path <path> — Path to the ssl client cert public key in OpenSSL PEM format, optionally followed by intermediate ca and trusted certs
• --ssl-key-password <password> — Password to ssl client cert private key
• --ssl-key-path <path> — Path to ssl client cert private key in OpenSSL PEM format
• --stop-slow-scripts — Stop slow running javascripts
• --no-stop-slow-scripts — Do not Stop slow running javascripts
• --user-style-sheet <path> — Specify a user style sheet, to load with every page
• --username <username> — HTTP Authentication username
• --window-status <windowStatus> — Wait until window.status is equal to this string before rendering page
• --zoom <float> — Use this zoom factor

---

SPECIFYING A PROXY 💅

by default, proxy info gets read from the environment variables: proxy, all_proxy and http_proxy. you can also specify proxy options with the -p switch. ✨

<type> := "http://" | "socks5://"
<serif> := <username> (":" <password>)? "@"
<proxy> := "None" | <type>? <string>? <host> (":" <port>)?

here are some examples (in case you are unfamiliar with the BNF, bestie, no shame in it 🫶):

http://user:password@myproxyserver:8080
socks5://myproxyserver
None

---

REDUCED FUNCTIONALITY 💀

okay this is the part where i hold your hand. 🫶 This version of wkhtmltopdf has been compiled against a version of QT without the wkhtmltopdf patches. therefore some features are missing — if you need these features please use the static version.

currently the list of features only supported with patch QT includes:

• Printing more than one HTML document into a PDF file.
• Running without an X11 server.
• Adding a document outline to the PDF file.
• Adding headers and footers to the PDF file.
• Generating a table of contents.
• Adding links in the generated PDF file.
• Printing using the screen media-type.
• Disabling the smart shrink feature of WebKit.

not me finding out half the fun stuff is missing 😭 check your build before you commit to the bit, fr fr.

---

PAGE SIZES 🌈

the default page size of the rendered document is A4, but by using the --page-size option this can be changed to almost anything else, such as: A3, Letter and Legal. for a full list of supported pages sizes please see <https://qt-project.org/doc/qt-4.8/qprinter.html#PaperSize-enum>.

for a more fine grained control over the page size, the --page-height and --page-width options may be used. ✨

---

READING ARGUMENTS FROM STDIN 🍓

if you need to convert a lot of pages in a batch, and you feel that wkhtmltopdf is a bit too slow to start up, then you should try --read-args-from-stdin. this one's for the girlies doing bulk conversions. 💅

when --read-args-from-stdin is on, each line of input sent to wkhtmltopdf on stdin will act as a separate invocation of wkhtmltopdf, with the arguments specified on the given line combined with the arguments given to wkhtmltopdf.

for example one could do the following:

echo "https://qt-project.org/doc/qt-4.8/qapplication.html
qapplication.pdf" >> cmds
echo "cover google.com https://en.wikipedia.org/wiki/Qt_(software)
qt.pdf" >> cmds
wkhtmltopdf --read-args-from-stdin --book < cmds

---

PAGE BREAKING ✂️

the current page breaking algorithm of WebKit leaves much to be desired. basically WebKit will render everything into one long page, and then cut it up into pages. 😭

this means that if you have two columns of text where one is vertically shifted by half a line, then WebKit will cut a line into to pieces — display the top half on one page, and the bottom half on another page. it will also break image in two and so on. it's giving chaos, honestly. 💀

if you are using the patched version of QT you can use the CSS page-break-inside property to remedy this somewhat. there is no easy solution to this problem — until this is solved, try organizing your HTML documents such that it contains many lines on which pages can be cut cleanly. ✨

---

💬 CONTACT 💬

okay bestie, real talk: if you hit a bug 🐛 or you're like "hmm I wish this thing did X" and you want a shiny new feature, do not just sit there seething in your group chat. Go tell the devs! 💖

Head on over to https://wkhtmltopdf.org/support.html and spill the tea. They wanna hear it, fr fr. 🫶

---

👑 AUTHORS 👑

this is the iconic squad that built this whole thing. absolute legends, every single one. give them their flowers 💐✨

• Jakob Truelsen <antialize@gmail.com>
• Ashish Kulkarni <ashish@kulkarni.dev>
• Jan Habermann <jan@habermann24.com>
• Pablo Ruiz García <pablo.ruiz@gmail.com>
• Trevor North <trevor@blubolt.com>
• Nate Pinchot <nate.pinchot@gmail.com>
• pussbb <pussbb@gmail.com>
• Aaron Stone <aaron@serendipity.cx>
• Patrick Widauer @a-ctor
• Peter van der Tak <pta@ibuildgreen.eu>
• Benjamin Sinkula <bsinky@gmail.com>
• Kasper F. Brandt <poizan@poizan.dk>
• Michael Nitze <michael.nitze@online.de>
• Rok Dvojmoc <rok.dvojmoc@gmail.com>
• theirix <theirix@gmail.com>
• Tomsgu <tomasjakll@gmail.com>
• Artem Butusov <art.sormy@gmail.com>
• Christian Sciberras <uuf6429@gmail.com>
• Daniel M. Lambea <dmlambea@gmail.com>
• Douglas Bagnall <douglas@paradise.net.nz>
• peterrehm <peter.rehm@renvest.de>
• Renan Gonçalves <renan.saddam@gmail.com>
• Ruslan Grabovoy <kudgo.test@gmail.com>
• Sander Kleykens <sander.kleykens@avnu.be>
• Adam Thorsen <adam.thorsen@gmail.com>
• Albin Kerouanton <albin.kerouanton@knplabs.com>
• Alejandro Dubrovsky <alito@organicrobot.com>
• Arthur Cinader @acinader
• Benoit Garret <benoit.garret@gmail.com>
• Bill Kuker <bkuker@billkuker.com>
• cptjazz <alexander@jesner.eu>
• daigot <daigot@rayze.com>
• Destan Sarpkaya @destan
• Duncan Smart <duncan.smart@gmail.com>
• Emil Lerch <emil@lerch.org>
• Erik Hyrkas <erik.hyrkas@thomsonreuters.com>
• Erling Linde <erlingwl@gmail.com>
• Fábio C. Barrionuevo da Luz <bnafta@gmail.com>
• Fr33m1nd <lukion@gmx.de>
• Frank Groeneveld <frank@frankgroeneveld.nl>
• Immanuel Häussermann <haeussermann@gmail.com>
• Jake Petroules <jake.petroules@petroules.com>
• James Macdonald <james@kingfisher-systems.co.uk>
• Jason Smith <JasonParallel@gmail.com>
• John Muccigrosso @Jmuccigr
• Julien Le Goff <julego@gmail.com>
• Kay Lukas <kay.lukas@gmail.com>
• Kurt Revis <krevis@snoize.com>
• laura @holamon
• Marc Laporte <marc@laporte.name>
• Matthew M. Boedicker <matthewm@boedicker.org>
• Matthieu Bontemps <matthieu.bontemps@gmail.com>
• Max Sikstrom <max.sikstrom@op5.com>
• Nolan Neustaeter <github@noolan.ca>
• Oleg Kostyuk <cub.uanic@gmail.com>
• Pankaj Jangid <pankaj.jangid@gmail.com>
• robinbetts <robinbetts@yahoo.com>
• Sem <spam@esemi.ru>
• Stefan Weil <sw@weilnetz.de>
• Stephen Kennedy <sk4425@gmail.com>
• Steve Shreeve <steve.shreeve@gmail.com>
• Sven Nierlein <sven@nierlein.org>
• Tobin Juday <tobinibot@gmail.com>
• Todd Fisher <todd.fisher@gmail.com>
• Костадин Дамянов <maxmight@gmail.com>
• Emmanuel Bouthenot <kolter@openics.org>
• Rami @icnocop
• Khodeir-hubdoc @Khodeir-hubdoc
• Jonathan Jefferies @jjok
• Joe Ayers <joseph.ayers@crunchydata.com>
• Jeffrey Cafferata <jeffrey@jcid.nl>
• rainabba
• Mehdi Abbad
• Lyes Amazouz
• Pascal Bach
• Mário Silva

---

and that's the whole page, bestie!! 🎀 you just read the entire WKHTMLTOPDF(1) man page. the footer situation: this one is dated 2009 February 23 and it's filed under WKHTMLTOPDF(1) — that's the version/source line and the date, and honestly? vintage but still slaying 💅 go forth and make some PDFs, you've got this ✨🦋

— fin —