wkhtmltopdf is a rather complex software, with multiple ways of installing it, many dependencies and many options. It's generally hard to find the perfect configuration to get rid of every issues. This document summarizes the way you can install it, frequent issues and how to solve them.
There're currently two versions available in the download section of wkhtmltopdf.org:
- Stable version (0.12.x), based on a patched version of Qt4, using a pretty old version of WebKit ;
- Bleeding edge version (0.13.x), based on a patched version of Qt5, using a relatively new version of WebKit,
But you may find another version in your distro's repositories. Generally speaking, it's a bledding edge version compiled without patched version of Qt5. Some distros, like Alpine, even use a version number that doesn't equate what has been released on wkhtmltpdf.org website (e.g. v0.14 in Alpine repositories, but newest is 0.13 on wkhtmltopdf.org).
Some wkhtmltopdf releases (which ones?) are fully headless: you don't need to run any X server prior to launch wkhtml. But other releases depends on an external X server, and in such case, you need to resort on a true X server or on xvfb (X virtual framebuffer).
The wkhtmltopdf package from Ubuntu repositories provides v0.12.3.2 (with unpatched qt5). You will need to install xvfb, xauth and libgl1-mesa-dri packages in order to run in headless mode.
To run it: xvfb-run -d -s "-screen 0 1024x768x24" wkhtmltopdf https://google.com /tmp/out/test.pdf.
As of now, there's a wkhtmltopdf package available in Ubuntu repositories but it is broken because it uses a deprecated version of OpenSSL. You should rather use the version available on wkhtmltopdf's website. You will need to install libxrender1 to make it working.
Alpine has a wkhtmltopdf package in its testing repository. It provides wkhtmltpdf v0.12.4-r0 with unpatched qt5. You will need dbus and xvfb package too, as well as fontconfig and freetype for proper font support, and mesa-dri-swrast for OpenGL support.
QXcbConnection: Could not connect to display
You need to either use xvfb-run to launch wkhtmltopdf, or manage to start a xvfb server and use it.
process 57: D-Bus library appears to be incorrectly set up; failed to read machine uuid: Failed to open "/etc/machine-id": No such file or directory See the manual page for dbus-uuidgen to correct this issue.
You need dbus, generally found under dbus package name.
libEGL warning: DRI2: failed to open swrast (search paths /usr/lib/xorg/modules/dri)
Search for a package with "mesa" and "dri" in its name and install it (for instance libgl1-mesa-dri for ubuntu/debian, mesa-dri-swrast for Alpine).
Warning: SSL error ignored
You miss root certificates, you need ca-certificates package.
libpng warning: iCCP: known incorrect sRGB profile
There's pretty much nothing to do if you don't own the images causing this error. If you have control over them, you can modify them following method described here.
If you try to render a long table it will span across multiple pages and you might see some rows overlapping each other. In that case you should add following CSS rules (accordingly to this issue, and this other one, and this Stack Overflow answer):
table { page-break-inside:auto }
tr { page-break-inside:avoid; page-break-after:auto }
thead { display:table-header-group }
tfoot { display:table-footer-group }If you have poor fonts support (or no font at all, like filled squares) you should install fontconfig and freetype packages.
Not all base64 encoder play well with your fonts. Some users seen better rendering when re-encoding their fonts with another encoder (accordingly to this comment).
For Windows, you should try to set the DPI to at least 200 (accordingly to this comment).
For Debian, CentOS, and maybe other Linux distributions, if you've got some font kerning issues you need to copy the following config into /etc/fonts/conf.d/10-wkhtmltodf.conf (accordingly to this comment). Also, check that fontconfig has been installed.
<?xml version='1.0'?>
<!DOCTYPE fontconfig SYSTEM 'fonts.dtd'>
<fontconfig>
<match target="font">
<edit mode="assign" name="rgba">
<const>rgb</const>
</edit>
</match>
<match target="font">
<edit mode="assign" name="hinting">
<bool>true</bool>
</edit>
</match>
<match target="font">
<edit mode="assign" name="hintstyle">
<const>hintslight</const>
</edit>
</match>
<match target="font">
<edit mode="assign" name="antialias">
<bool>true</bool>
</edit>
</match>
<match target="font">
<edit mode="assign" name="lcdfilter">
<const>lcddefault</const>
</edit>
</match>
</fontconfig>