How to resolve "Cannot create a QPixmap when no GUI is being used" when running wkhtmltopdf

Few days ago, I got a request from my customer to make changes to PDF exporting feature which involve putting watermark inside PDF file. The existing setup in the project was like this: all necessary information are presented in HTML file and then this HTML file is converted into PDF using wkhtmltopdf program (

Because I wanted to render images as watermark in HTML, I had to use opacity CSS property to create the effect. And although I could successfully export my HTML to PDF on my computer, I got the following error message on server

Cannot create a QPixmap when no GUI is being used

The problem could be because there are no GUI on server when wkhtmltopdf is running and it does not know how to render opacity property correctly.

After a little research, two solutions were suggested and both of them worked pretty well in my case

  1. Upgrade (or downgrade) your wkhtmltopdf version

The version of wkhtmltopdf on my server at that time was 0.9.0 and it did not work well with opacity property. And according to several suggestions here, I tried upgrading wkhtmltopdf version to 0.10.0_rc2. Then everything would work as I expected. I am not sure, however, about other versions because I also saw several comments about other newer versions such as 0.11.0 that did not work with opacity property. So, if you don't know which version to choose, I suggest using 0.10.0_rc2 as your choice.

Link to list of available downloads:
2. Using X Server to export your PDF

Another solution is to add --use-xserver option when running wkhtmltopdf. Be noted that you will need to install xvfb package on server and execute a slightly different way, if you run wkhtmltopdf directly, you might see the following error message:

wkhtmltopdf: cannot connect to X server

In my project, instead of running wkhtmltopdf directly from terminal, I create a bash script to execute it via xvfb-run like this

xvfb-run -a -s "-screen 0 1024x768x24" wkhtmltopdf "$@"

I can create a file called with above content and then I can invoke it like this

sh <options>

You can put any possible options supported by wkhtmltopdf as an option when running this bash and everything would behave as we expected.

You can read more about this solution here:

Hope these information could be helpful to you. Let me know if you found another solutions for this issue.