Convert HTML to PDF with wkhtmltopdf

25 June 2025
#pdf-generation
This post thumbnail

Quick Start

wkhtmltopdf is a command-line tool that converts HTML to PDF. It's been around for years and is probably the most popular tool in it's category.

To get started, download it from the whhtmltopdf releases page on github.

Basic usage:

# Convert a website to PDF
wkhtmltopdf https://transformy.io transformy.pdf

# Convert local HTML file
wkhtmltopdf index.html output.pdf

# Add margins and headers
wkhtmltopdf --margin-top 20mm --header-right "Page [page]" https://transformy.io output.pdf

What is wkhtmltopdf?

wkhtmltopdf is a command-line tool that converts HTML to PDF using the Qt WebKit rendering engine. Somewhat like a browser, it can render HTML, CSS and Javascript. It comes with a very simple API, runs headless, and is relatively easy to integrate into your existing stack. The license (GPL v3.0) is also very permissive.

Be warned though: wkhtmltopdf relies on QT webkit which isn't actively maintaned anymore. This means that small rendering issues might pop up considering how fast web technologies evolve. Sites built with modern JavaScript frameworks or SPAs in particular might not render as expected (React, Vue...). However, for most HTML documents and simpler websites, it works really well.

Installing wkhtmltopdf

First off you'll need to install the package on your machine.

macOS

On macOS this *used to be straightforward usign brew. But because wkhtmltopdf hasn't been updated in a while, running brew install --cask wkhtmltopdf will give you the following error message:

Error: Cask 'wkhtmltopdf' has been disabled because it is discontinued upstream! It was disabled on 2024-12-16.

What you need to do instead:

  1. Head over to the releases page and download the one for macOS.
  2. Double clickon the .pkg file
  3. You'll likely see another error: "Apple could not verify "wkhtmltox-0.12.6-2.macos-cocoa.pkg" is free of malware that may harm your Mac or compromise your privacy."
  4. Close the error window and head on over to System Settings -> Privacy & Security -> Scroll down to Security. There, you'll see a message saying the packages was blocked. Click on "Open Anyway"
  5. The installer should now have launched and you can continue with the installation.

wkhtmltopdf version output

Windows

For Windows installation:

  1. Download the installer from the releases page
  2. Run the installer

The installer will add wkhtmltopdf to your PATH automatically

Linux

On Linux the exact steps for installation will vary depending on your distro. Here's how to get it running on Ubuntu 22.04

This is an example using amd64. Depending on your architecture you will need a different version. You can find all available versions on the releases page.

apt install wkhtmltopdf

wget https://github.com/wkhtmltopdf/packaging/releases/download/0.12.6.1-2/wkhtmltox_0.12.6.1-2.jammy_amd64.deb

sudo dpkg wkhtmltox_0.12.6.1-2.jammy_amd64.deb

Finally, make sure you don't have any broken dependencies and run:

sudo apt install -f

Verify installation

wkhtmltopdf --version

wkhtmltopdf version output

If you see the version info, you're good to go.

How to use wkhtmltopdf

Now that you have wkhtmltopdf installed, let me walk you through how to use it effectively.

The basic pattern

Every wkhtmltopdf command follows this structure:

wkhtmltopdf [options] <input> <output>

Common use cases

Converting a website to PDF:

wkhtmltopdf https://stripe.com/docs/api stripe-api-docs.pdf

Converting a local HTML file:

wkhtmltopdf invoice.html invoice.pdf

Combining multiple pages into one PDF:

wkhtmltopdf page1.html page2.html page3.html combined.pdf

Useful options for better results

Page setup:

# A4 paper in landscape orientation
wkhtmltopdf -s A4 -O Landscape input.html output.pdf

# Custom margins for professional documents
wkhtmltopdf -T 15mm -B 15mm -L 10mm -R 10mm input.html output.pdf

Adding headers and footers:

# Page numbers
wkhtmltopdf --footer-center "Page [page] of [topage]" input.html output.pdf

# Date stamps
wkhtmltopdf --footer-left "[date]" --footer-font-size 9 input.html output.pdf

Controlling output quality:

# High-quality for printing
wkhtmltopdf --dpi 300 --print-media-type input.html output.pdf

# Optimized for file size
wkhtmltopdf --lowquality --image-quality 75 input.html output.pdf

Handling JavaScript-heavy sites

Many modern websites load content dynamically with JavaScript. By default, wkhtmltopdf waits 200ms to capture the page, which in some cases might not be enough. You can overwrite this:

# Give JavaScript time to execute
wkhtmltopdf --javascript-delay 3000 https://transformy.io report.pdf

The delay is in milliseconds. Start with ~3000 (3 seconds) and adjust based on the site's loading time. Obviously this will have an impact on the total processing time.

In some cases you might not want to run javascript at all. You can disable it with --disable-javascript.

Working with authenticated pages

If you need to convert pages that require login:

# Basic HTTP authentication
wkhtmltopdf --username transformyadmin --password secret666 https://secured.transformy.io report.pdf

# Cookie-based authentication
wkhtmltopdf --cookie session_id "435843285" https://app.transformy.io report.pdf

Advanced techniques

If you've got the basics down, there's some pretty neat advanced features wkhtmltopdf offers with which offer a lot of customization options for your PDF output.

Generating a table of contents

For longer documents like reports or documentation, you can automatically generate a table of contents. The table of contents will be based on the headings used in the HTML.

wkhtmltopdf toc input.html output.pdf

Appending HTML headers and footers

You can create a custom header or footer with HTML and use wkhtmltopdf to stich it together with the content when generating your PDF.

# Create a header.html file with your custom design
wkhtmltopdf --header-html header.html --header-spacing 5 content.html output.pdf

Debugging rendering issues

When a PDF doesn't look right, these debugging options help identify the problem:

# View JavaScript console output
wkhtmltopdf --debug-javascript input.html output.pdf

# Export the document outline
wkhtmltopdf --dump-outline outline.xml input.html output.pdf

Common issues and solutions

While implementing wkhtmltopdf for transformy, I've run into some small issues.

Poor font rendering

Installing proper fonts usually fixes this:

# Ubuntu/Debian
sudo apt-get install fonts-liberation

# CentOS/RHEL
sudo yum install liberation-fonts

CSS files not loading

Ensure your HTML uses absolute paths or includes a base tag. If you don't own the website and aren't able to add a base tag, you might need some pre-process to edit the html before passing it to wkhtmltopdf.

<base href="https://transformy.io/">

Controlling page breaks

Add these CSS rules to your HTML:

.page-break { page-break-after: always; }
.keep-together { page-break-inside: avoid; }

When wkhtmltopdf might not be enough

whhtmltopdf is a workhorse, but there's some scenarios where you might need to grab a different solution.

For one, it doesn't support interactive PDF forms. If that's something you need I recommend trying pdftk.

As mentioned earlier though, the biggest issue will be javascript heavy websites. In that case the a better solution is to use Headless Chrome to print your pages.