Wkhtmltopdf font and sizing issues

Wkhtmltopdf does a pretty good job at converting HTML documents to PDF. It does have a few oddities however when it comes to getting consistent font sizing. Namely, you may find that the tool generates PDFs at different scales on different computers. So for example, everything looks right on your development machine, but when you deploy to a test server or production, everything looks like it's zoomed in.

I haven't read enough about it's architecture to know how it works exactly, but I believe it takes the HTML input and passes it to a WebKit rendering engine, which actually renders the HTML to some virtual or hidden browser window, and then it simply prints the state of that browser window to PDF using a QT driver.

Just like a real browser window though, unless you specify exact fixed widths for your HTML containers, the contents will get wrapped to try and fit without any horizontal scrolling. The default width of this internal browser is dependent on the resolution of your actual machine. So on your development system, this may be something like 1600x1050, but on your headless test/production system (which may not even have a graphical interface), the default resolution will be something like 640x480. So when you generate the PDFs on your development machine they may come out very small, but when you move over to production, everything gets enlarged.

The fix for this is to set a constant fixed width to your HTML page container with CSS.

You may also want to us the flag --disable-smart-shrinking which disables "the intelligent shrinking strategy used by WebKit that makes the pixel/dpi ratio none constant".

Another problem you may face is different fonts from one system to the next. This is because the WebKit engine uses whatever fonts are on your computer to render the HTML. So if you're using say "Times New Roman" in your CSS, this may work fine on your Windows development machine, but this font will most likely not be installed on a headless Linux server, so the WebKit engine may decide to default to a Serif font. You need to install the right fonts on whatever machine the tool is running on.

Another got-cha is that the WebKit engine used seems to be picky with the font-family CSS setting. Namely, it seems to only accept a font-family with a single entry, e.g.

body {
  font-family: "serif";

If you try and list multiple families separated by commas, they'll be ignored.

And finally, you need to make sure your HTML document either specifies the encoding type in a META tag, or  else pass the encoding type explicitly to wkhtmltopdf using the --encoding flag (e.g. --encoding utf-8). I believe if both a META tag is found, and also the --encoding flag, it will only use the META tag.


  1. omfg..you saved me :D

  2. Banging my head on the table before finding this post. Thanks for the help.

  3. Great suggestions!

  4. Fixed width and single font family - solved all my kerning issues. Thanks!

  5. just saved me lots of hours, thanks...

  6. Thanks man, solved a problem I had for months!

  7. The bit about setting a width on the HTML element to get it to emulate a certain browser scale was genius. I spent a couple hours pouring over the documentation trying to figure out how to do this. Wish I'd found this sooner! Thanks.

  8. You saved me hours of testing, thanks a lot !!!

  9. After suddenly having scaling issues with a server that has never had them, I discovered that the issue is DEFINITELY UI scaling. My laptop has a 3000x2000 display that uses 200% (of 96DPI) scaling while my desktop uses 100%/96DPI. When I RDP'd to the server with my LAPTOP, the console session took on that scaling (even though it still reported 100% in display properties). When I logged out and back in again from my desktop, the scaling was good again. My reports ARE already fixed dimensions and before I realized the "fix", I played with zoom which did make a difference, but it's relative to UI scaling. All this was with WKHTMLTOPDF 12.3 dev. This is being discussed at: https://github.com/wkhtmltopdf/wkhtmltopdf/issues/1782

  10. `--disable-smart-shrinking` is apparently the only way to have `12pt` fonts that are actually 12 points. Thanks a lot for the hint.

  11. You can get rid of this issue by using the 32 bit version of wkhtmltopdf converter :) . Same issue rose at my workplace, got it solved that way (y)

  12. thank you people, I was struggling with the same issue. Now it's gone :)

  13. "--disable-smart-shrinking"
    viola its solved my problem...


Post a Comment

Popular posts from this blog

Import Google Contacts to Nokia PC Suite

Can't delete last blank page from Word