wkhtmltopdf setup guide with KnpLabs Snappy support on Debian

This document will show you how to get wkhtmltopdf working on Debian using KnpLabs Snappy. If you try and install from distribution you won’t get some of the latest features of wkhtmltopdf like {shell}–javascript-delay{/shell}. This guide will help you install the latest version {shell}0.11.0 rc1{/shell}. This guide assumes you have LAMP already installed and that you can run {shell}sudo{/shell}.

1. Installing dependencies

Before you install you will need to have X11, gcc and openssl installed.

2. Getting the source

The bleeding edge build from git didn’t work for me so let’s download the latest stable release build.

Let’s make a temp directory

Download and extract the code by running

Be sure to change the version number to the latest source release.

3. Installing QT

Before you can compile wkhtmltopdf you need to have QT installed, again you have two options: You can install the QT from your distribution, this will be fast but your wkhtmltopdf build will not have all the features of the static build, or you can compile QT your self, this takes a long time but you will get all the features.

NOTE: I would suggest installing from distribution (3.b). I tried installing from source and it didn’t work.

3.a Installing QT from your distribution

You must now run qmake in the wkhtmltopdf folder.

3.b Installing QT yourself

First check out the source

Qt must be configured, a good set of configuration options for qt can found by looking at the output of

And Qt compiled and installed (this will take a while)

You must now run qmake in the wkhtmltopdf folder.

4. Compiling and installing wkhtmltopdf

Now all you need to do is compile and install wkhtmltopdf

For some reason Debian wants execute from

. So do the following to fix the issue.

6. Check to see if it works

Run the following. If you get the error {shell}”Cannot connect to X server”{/shell} then continue to number 7.

7. Fixing “Cannot connect to X server”

We need to run it headless on a ‘virtual’ x server. We will do this with a package called xvfb.

8. Create a shell script wrapper for wkhtmltopdf

We need to write a little shell script to wrap wkhtmltopdf in xvfb. Make a file called wkhtmltopdf.sh using the following:

Now let’s make it executable.

Give step 6 a try again.

Using KnpLabs Snappy

Here I will show you how to use KnpLabs Snappy. Snappy is a PHP5 library allowing thumbnail, snapshot or PDF generation from a url or a html page. It uses the excellent webkit-based wkhtmltopdf and wkhtmltoimage available on OSX, linux, windows.

1. Download snappy from github

2. Copy the {shell}snappy-master/src{/shell} folder to your webroot.

3. Create a html file for your template

Save this file as {shell}hello.html{/shell} in your webroot. This will be used as your template. It contains a chart from hicharts.js.


In order for wkhtmltopdf to correctly print the chart, it is advised to remove any animations on hicharts.js objects. You will need to set the {javascript}animation{/javascript} property to false for both the {javascript}Chart{/javascript} object and the {javascript}plotOptions.series{/javascript} object.

4. Create the following php file in your webroot.

Save this file as {shell}generate-pdf.php{/shell} in your webroot.


Note the use of {php}javascript-delay{/php}:

This will allow you to delay the printing of the pdf for a specified amout of time defined by ms. In this case the delay is set to {php}500ms{/php}. Also the {php}Content-Disposition{/php} is set to {php}inline{/php}. This will allow the pdf to show withing the browser window if the user has a pdf plugin installed. Supported browsers are Chrome and Safari. If the user does not have a supported browser they will be presented with a file download diaglog.


December 3, 2012
1:26 am

Comments are closed.