Skip to content

Browse PDFs in a Qt Widgets application

Some months ago Shawn Rutledge blogged about the new QtPdf module, a Qt wrapper around the PDFium library, which allows you to render PDF documents to QImages. Since that blog post we have invested some more work into the module to make it more useful in your day-to-day projects.

One long-standing bug report against Qt is QTBUG-28886, which is about adding a widget to Qt that can easily render a PDF document. That does not only involve rendering of single pages, but also to provide ways to navigate through the document, so say hello to…


QPdfView is a widget that renders a PDF document that has been loaded through QPdfDocument. It offers a single page and a continuous multi page mode and the user can choose between fit-to-width, fit-in-view or a custom zoom level.

PDF QtWidgets PDFium, Browse PDFs in a Qt Widgets application

To avoid the UI getting blocked while the PDF document is rendered, the rendering of the single pages is off-loaded to a worker thread.

Getting the code

To test the new features, just clone the QtPdf repository, install it and compile the examples like this:

git clone git://
cd qtpdf
git submodule update --init --recursive
cd examples/pdf/pdfviewer


Using QPdfView is quite simple – loading a PDF document and showing it on screen can be done in a couple of lines now:

#include <QPdfDocument>
#include <QPdfView>

QPdfDocument *document = new QPdfDocument;

QPdfView *view = new QPdfView;

If you want to see a more extensive example, have a look at the examples/pdf/pdfviewer directory in the QtPdf module.

Next steps

At the moment the PDFium version which is shipped with QtPdf is rather outdated, and therefore does not include the latest security fixes from upstream. The blocking factor from upgrading it is PDFium’s build system, which has changed from gyp to gn; the build system integration inside QtPdf hasn’t followed up yet.

Thankfully, Michal Klocek from The Qt Company provided the first patches that allow us to implement a proper integration between qmake and gn, so that compiling the QtPdf module with an up-to-date PDFium version should be much easier in the future.

On the UI side there are many things to do as well, here just a short selection from the top of my head:

  • extend navigation possibilities (e.g. follow links, navigate to sections)
  • add custom QtQuick item to render PDF pages (patches in progress already)
  • extend and improve documentation.

Nonetheless, I hope this module will be useful to the many users who are looking for an easy solution to render PDF documents in their Qt applications!

About KDAB

KDAB is a consulting company offering a wide variety of expert services in Qt, C++ and 3D/OpenGL and providing training courses in:

KDAB believes that it is critical for our business to contribute to the Qt framework and C++ thinking, to keep pushing these technologies forward to ensure they remain competitive.


17 thoughts on “Browse PDFs in a Qt Widgets application”

  1. Just tip for someone who met issue (error during building) like below:
    ../3rdparty/pdfium/third_party/freetype/src/base/ftbase.c:19:10: fatal error: ft2build.h: No such file or directory

    This happens only when you use python3. If your main python is python2 you should be able to build QtPdf.
    For all who use python3 workaround is making link to python2 (just temporary relink /usr/bin/python to python2).
    Sad is that, I reported this issue over one year ago (January 2017) and nobody fixed this yet :(.

    1. Tobias Koenig

      Hej Peter,

      thank you very much for the hint, I haven’t seen your comment on Shawns blog post, so I missed the fact that the current build system does not work with Python 3. Anyway, since the next step will be to update the build system to use gn (to be compatible with upstream PDFium), this Python script will be replaced and therefore the problem hopefully be solved soon.

  2. Isn’t better just to use this library “poppler” (exists poppler-qt5 which is Qt5 bindings) instead of build qtpdf?

    1. Tobias Koenig

      Hej Peter,

      the Poppler library is distributed under the GPL license, so it cannot (easily) be used in proprietary projects.
      Furthermore the PDFium library is actively maintained by Google (since it is used by Chromium to render PDFs) and for graphic intensive documents it renders the pages much faster than Poppler.

  3. Is there any possibility of something like a QPDFGraphicsItem that could be used in a QGraphicsView rather than requiring a dedicated view widget for just this type of object? Or does the underlying PDF library make it impractical to provide that kind of deeper Qt integration beyond a widget to view what the library spits out?

    1. Tobias Koenig

      Hej Will,
      the QPdfDocument class allows you to render a specific page (or part of a page) into a QImage, so it shouldn’t be too difficult to reimplement a QGraphicsItem subclass which utilizes this function to display parts of a PDF document. However, at the moment the QtPdf module doesn’t provide a convenience class for it, but upstream contributions are always welcome 🙂

  4. On openSuse I get the following errors:
    cd lib/ && ( test -e Makefile || /usr/bin/qmake-qt5 -o Makefile /home/PACKAGES/qt/5.9.2/src/qtpdf/src/lib/ ) && make -f Makefile
    Traceback (most recent call last):
    File “/home/PACKAGES/qt/5.9.2/src/qtpdf/src/3rdparty/”, line 162, in
    gyp = Gyp(config.input, variables)
    File “/home/PACKAGES/qt/5.9.2/src/qtpdf/src/3rdparty/”, line 7, in __init__
    with open(fileName, “r”) as f:
    IOError: [Errno 2] No such file or directory: ‘/home/PACKAGES/qt/5.9.2/src/qtpdf/src/3rdparty/pdfium/pdfium.gyp’
    Traceback (most recent call last):
    File “/home/PACKAGES/qt/5.9.2/src/qtpdf/src/3rdparty/”, line 162, in
    gyp = Gyp(config.input, variables)
    File “/home/PACKAGES/qt/5.9.2/src/qtpdf/src/3rdparty/”, line 7, in __init__
    with open(fileName, “r”) as f:
    IOError: [Errno 2] No such file or directory: ‘/home/PACKAGES/qt/5.9.2/src/qtpdf/src/3rdparty/pdfium/third_party/third_party.gyp’
    Cannot read /home/PACKAGES/qt/5.9.2/src/qtpdf/src/lib/pdfium.pri: No such file or directory
    Cannot read /home/PACKAGES/qt/5.9.2/src/qtpdf/src/lib/freetype.pri: No such file or directory
    and later also
    jsbridge.cpp:37:50: fatal error: fpdfsdk/javascript/JS_Runtime_Stub.cpp: No such file or directory

    1. Tobias Koenig

      Hej Martin,
      have you initialized the submodules correctly (e.g. called ‘git submodule update –init –recursive’)? Looks like your ‘qtpdf/src/3rdparty/pdfium/’ directory is empty, which indicates that the pdfium submodule has not been cloned.

  5. Thanks Tobias, It’s been a long time since my original request of having a PDF viewer (QTBUG-28886) and I am glad to see it starting to happen. As soon as the new build system is in place, I plan on dedicating time on adding form editing to your QtPDF module wrapper to take advantage of these features in PDFium.

  6. Can you also use QPdfDocument to create a PDF by code and save it? QPdfWriter unfortunately has one severe restriction – no bookmarks and links.

    1. Tobias Koenig

      Hej Robert,
      QPdfDocument only provides API do render PDF documents, but not to assemble them.
      Links are ‘kind of’ supported by QPdfWriter, the QPdfEngine class has a member drawHyperlink(QRect, QUrl), so when you use a QPainter that draws on a QPrinter in PDF output mode and include the private header qpdf_p.h, you could do dynamic_cast<QPdfEngine*>(painter.paintEngine())->drawHyperlink(...). So it is private API which can be accessed on your own risk. 😉

Leave a Reply

Your email address will not be published. Required fields are marked *