How to render HTML into PDF using
wkhtmltopdf

What is wkhtmltopdf? ​

Wkhtmltopdf is a command-line tool that renders HTML to PDF using a WebKit rendering engine. Many libraries that offer this feature are built on top of it.

However, we recommend using it at your own risk.

Wkhtmltopdf's last stable release came out in June 2020. The project has since been deprecated and archived on GitHub.

This means security patches, JavaScript features, and CSS features added after 2020 are unlikely to be supported by wkhtmltopdf. Newly discovered bugs or security issues may also remain unpatched. As a result, code that looks correct in your browser can still break when rendered to PDF.

Setup ​

Start by installing the command line tool on your machine.

You can find precompiled binaries here, but they can be old and may not be compatible with your current machine.

Another option is to build it from the source.

On macOS, you can install it with Homebrew:

brew install wkhtmltopdf --cask

Usage ​

The wkhtmltopdf command line is straightforward:

wkhtmltopdf <source> <output>

The source can be either a URL or the relative path to an HTML file. The output is the relative path to the generated PDF file.

A lot of options are available. You can find the whole list here.

Restrictions ​

Pure HTML ​

Wkhtmltopdf does not work well with JavaScript-heavy pages. If you use a framework such as Vue, React, or Angular to render the HTML, the resulting PDF may be incomplete or blank.

Security issues ​

Using wkhtmltopdf in your application means adding another dependency and executing a binary alongside your application. That can introduce additional security risk.

The documentation warns not to use it with untrusted HTML, because it could compromise the server it runs on. It is your responsibility to validate and sanitize the HTML to reduce that risk.

Automation ​

It is not the most suitable approach if you are trying to automate PDF generation for workflows such as invoices or reports. Other libraries wrap wkhtmltopdf for easier use in Node, Python, and other ecosystems, but that adds another layer of complexity and may limit some features.

Deprecated ​

As mentioned earlier, wkhtmltopdf is no longer maintained. That means no future updates are expected. If a security issue or bug is discovered, it may never be fixed.

Wkhtmltopdf vs Doppio ​

For a full comparison and migration guide, see our wkhtmltopdf alternative article.

Doppio provides a simpler, more secure, and more scalable way to render PDFs.

All it takes to render a PDF is an API call.

It is easy to use and kept up to date with the latest rendering engines by our team.

It runs outside your application, which can reduce resource usage on your server and limit exposure to some security risks.

You can easily use Doppio from your terminal with just curl, without installing anything.

curl --location --request POST 'https://api.doppio.sh/v1/render/pdf/direct' \
--header 'Authorization: Bearer <YOUR API KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "page": {
    "pdf": {
      "printBackground": true
    },
    "goto": {
      "url": "https://example.doppio.sh/information-booklet.html",
      "options": {
        "waitUntil": ["networkidle0"]
      }
    }
  }
}' --output ./myfile.pdf