Qt for Python Getting Started

This page is focused on building Qt for Python from source, if you just want to install PySide2 with pip you need to run:

pip install pyside2

for more details, refer to our Quick Start guide.

General Requirements

  • Python: 3.5+ and 2.7

  • Qt: 5.12+ is recommended

  • libclang: The libclang library, recommended: version 6 for PySide2 5.12. Prebuilt versions of it can be downloaded here.

  • CMake: 3.1+ is needed.

Guides per platform

You can refer to the following pages for platform specific instructions:

  • Windows,

  • macOS,

  • Linux,

  • Mobile platforms (iOS/Android) (no support)

  • Embedded platforms (no official support)


    Most Linux-based embedded OS provide PySide2 with their official package manager (e.g. Raspbian and ArchlinuxARM).

A normal building command will look like this:

python setup.py install --qmake=/path/to/qmake \
                        --ignore-git \
                        --debug \
                        --build-tests \
                        --parallel=8 \
                        --make-spec=ninja \
                        --verbose-build \

Which will build and install the project with debug symbols, including the tests, using ninja (instead of make), and considering only the module subset of QtCore, QtGUI and QtWidgets.

Other important options to consider are:
  • --cmake, to specify the path to the cmake binary,

  • --reuse-build, to rebuild only the modified files,

  • --openssl=/path/to/openssl/bin, to use a different path for OpenSSL,

  • --standalone, to copy over the Qt libraries into the final package to make it work on other machines.

Testing the installation

Once the installation finishes, you will be able to execute any of our examples:

python examples/widgets/widgets/tetrix.py

Running Tests

Using the --build-tests option will enable us to run all the auto tests inside the project:

python testrunner.py test > testlog.txt


On Windows, don’t forget to have qmake in your path (set PATH=E:\Path\to\Qt\5.14\msvc2017_64\bin;%PATH%)

You can also run a specific test (for example qpainter_test) by running:

ctest -R qpainter_test --verbose

Building the documentation

The documentation is being generated using qdoc to get the API information, and also sphinx for the local Python related notes.

The system required libxml2 and libxslt`, also on the Python environment, sphinx and graphviz need to be installed before running the installation process:

pip install graphviz sphinx

After installing graphviz`, the ``dot command needs to be in PATH, otherwise, the process will fail. Installing graphviz system-wide is also an option.

Since the process rely on a Qt installation, you need to specify where the qtbase directory you will use with your qmake is located:

export QT_SRC_DIR=/path/to/qtbase

Once the build process finishes, you can go to the generated *_build/*_release/pyside2 directory, and run:

make apidoc

Finally, you will get a html directory containing all the generated documentation.