Migration guides · Python

Replace `wkhtmltopdf` with pdfkiln in `imgkit`

imgkit takes page screenshots with wkhtmltoimage, which pdfkiln provides beside wkhtmltopdf, with the same 63 options.

1. Install pdfkiln

On Debian and Ubuntu, amd64 and arm64: the signed APT repository installs /usr/bin/wkhtmltopdf in place of the wkhtmltox package, and brings Chromium’s fixes with apt upgrade.

curl -fsS https://apt.pdfkiln.org/pdfkiln-archive-keyring.asc | sudo tee /usr/share/keyrings/pdfkiln-archive-keyring.asc > /dev/null
printf 'Types: deb\nURIs: https://apt.pdfkiln.org\nSuites: stable\nComponents: main\nSigned-By: /usr/share/keyrings/pdfkiln-archive-keyring.asc\n' \
  | sudo tee /etc/apt/sources.list.d/pdfkiln.sources
sudo apt update && sudo apt install pdfkiln

Elsewhere: the Docker image, the archives and the Windows installer.

2. Point `imgkit` at it

import imgkit

# Nothing to do if wkhtmltoimage is in the PATH
imgkit.from_url('https://example.com', 'out.png')

# Otherwise, give its path
config = imgkit.config(wkhtmltoimage='/usr/bin/wkhtmltoimage')
imgkit.from_string(html, 'out.jpg', config=config)

3. Check

wkhtmltopdf --version
# wkhtmltopdf 0.12.6 (with patched qt), pdfkiln 1.0.4, Chromium 156.0.8078.80

The answer starts as wkhtmltopdf 0.12.6’s does: libraries that read the version keep working.

What `imgkit` expects, and what pdfkiln does

Formats: jpg (the default on standard output), png, bmp, ppm, xpm, xbm and svg, from --format or the extension; the SVG embeds a PNG. tif, gif and webp give Could not save image, as with wkhtmltoimage.
Width: the screen’s, 1024 pixels by default, widened while the content overflows (smart width). Height: the content’s.
Under a page whose body hides its overflow (Odoo reports, for instance), wkhtmltoimage added thousands of blank pixels; pdfkiln stops at the content.

Tested

imgkit 1.2.3’s suite passes 43 of 43 tests on wkhtmltoimage, as with wkhtmltoimage 0.12.6 (without its tests of xvfb and of github.com, which the test container cannot reach).

Something renders differently? Open an issue with the HTML and both PDFs: github.com/Jamalofski/pdfkiln/issues. The known differences are listed in the README.

Replace wkhtmltopdf with pdfkiln in imgkit