Table of Contents

Using Shiboken2 to create Python bindings for a Qt library


With the release of Qt 5.12, Qt for Python is officially supported and can be used to write full-fledged Qt applications using Python as the main programming language.

This prompted us to also take a closer look at the bindings (the Python module is called PySide2) and also the underlying technology, namely the binding generator called Shiboken2.


The Qt bindings themselves are easy to install and to use. If you have a python interpreter and the pip package manager set up on your system, whether it is Windows or Linux, you can install the module via pip install PySide2 and are ready to go.


While it is nice to use the Qt framework from Python it is even better to be able to quickly create Python bindings for your own Qt libraries and use their API from Python with relatively little work.

Getting started

All examples on this article have been run on Ubuntu 18.04, the setup steps for other platforms might vary.

Since the most recent documentation advises to build Shiboken2 from source for building your own bindings, we will do that now.


This posts assumes that you have a Qt 5.12 installation ready at $HOME/Qt/5.12.0/gcc_64/, which is the default location when using the online installer from

“If you use Qt from a different location adjust the paths accordingly.”

Install all required tools and libraries

The following apt command line works for Ubuntu 18.04 and should be a good starting point for other distributions.

sudo apt update
sudo apt install llvm-6.0 virtualenvwrapper python3 python3-dev cmake build-essential git clang-6.0 libclang-6.0-dev libxslt-dev mesa-common-dev libgl1-mesa-glx libglib2.0-0 wget 

# We require CMake >= 3.12 due to the improved Python support 

tar xvf cmake-3.13.2-Linux-x86_64.tar.gz 

export PATH=$PWD/cmake-3.13.2-Linux-x86_64/bin/:$PATH 

Get the sourcecode

The fastest way to get the PySide2 and Shiboken2 source is to clone the git repository.

git clone git://
cd pyside-setup
git checkout 5.12.0
git submodule update --init 

Set up a python virtualenv

We advise you to work in python virtual environments, as that will keep your system installation clean and you should be able to do anything else in this post without requiring root privileges.

source /etc/bash_completion.d/virtualenvwrapper
mkvirtualenv -p `which python3` pyside2build 

This will set up a python3 virtual environment in your home directory (~/.local/share/virtualenvs/pyside2build) and activate it. Your shell should have a prefix indicating that. To activate the virtualenv in the future use: 

workon pyside2build 


Now that we have prepared everything, the actual build is easy.

# Change into your clone of pyside-setup.git
cd pyside-setup

# Adjust the jobs parameter for the number of cores on your system
python install --qmake=$HOME/Qt/5.12.0/gcc_64/bin/qmake --jobs=8 

After the build has finished, which can take some time, you should have a fully working and properly linked PySide2 and Shiboken2 installation in your virtualenv.

Verify our build 

Try it by running the shiboken2 command line tool:

(pyside2build) swid@spica:~/src/pyside-setup (5.12)$ shiboken2
shiboken: Required argument header-file is missing.Command line: 

If you see output similar to this, you are good to go.

Wrapping your library with Shiboken2

Note: All files mentioned in this section can be cloned at GitHub. Clone the repository!

Shiboken2 requires mainly three things to work:

The library to generate bindings for.

An ‘entry-point’ header file which includes all other headers of classes for which bindings are generated for.

A type description XML file which (at a minimum) tells shiboken which types to wrap.

The library

Our trivial library contains only a single QObject with signals, slots and a Q_ENUM which is used in the API. Checkout the source code for implementation details.


#pragma once
class QObjectWithEnum : public QObject
    enum class MyEnum {
    explicit QObjectWithEnum(QObject *parent = nullptr);
    QString nonSlotFunction(const MyEnum value) const;
    void someSignal(QString stringArg);
public slots:
    void aSlot();


#include "qobjectwithenum.h"


QObjectWithEnum::QObjectWithEnum(QObject *parent) : QObject(parent)

QString QObjectWithEnum::nonSlotFunction(const QObjectWithEnum::MyEnum value) const {
    const auto ret = metaObject()->enumerator(0).valueToKey(int(value));
    qDebug() << __FUNCTION__ << "returning:" << ret;
    return ret;

void QObjectWithEnum::aSlot() {
    qDebug() << __FUNCTION__ << "slot called";
    emit someSignal("from aSlot");

The ‘entry-point’ header file

Our ‘entry-point’ header pulls in the required library headers, which is pretty simple in our case, and also sets up a define required for generating code for the Qt specialities.


#define QT_ANNOTATE_ACCESS_SPECIFIER(a) __attribute__((annotate(#a)))
#include "qobjectwithenum.h" 

The typesystem description

Although the typesystem description XML file can do much more than just describe which types to expose, we will stick to a rather simple version within our example.


<?xml version="1.0"?>

<typesystem package="Shiboken2QtExample">
    <load-typesystem name="typesystem_core.xml" generate="no"/>
    <object-type name="QObjectWithEnum">
        <enum-type name="MyEnum" />

Generate the bindings

Note: CMake >= 3.12 is required here.

To simplify building and linking all the parts we adapt a CMakeLists.txt file from the sample bindings example.

The example CMakeLists.txt installs the resulting library into the source folder and adds all relevant paths as RPATHS for the built libraries which makes local usage convenient.


cmake_minimum_required(VERSION 3.12)
cmake_policy(VERSION 3.12)

find_package(Qt5 REQUIRED Core)

get_target_property(QtCore_location Qt5::Core LOCATION)
get_filename_component(QtCore_libdir ${QtCore_location} DIRECTORY)




The CMake build file has been adapted from the official sample binding. The content is not relevant to this article. It can be found in the downloadable zip.

Make a shadow build and install

mkdir build
cd build
cmake ..
make install 

Using the module

Now that the bindings have been generated and built we can write a python script which uses the new binding module.

from Shiboken2QtExample import *
a = QObjectWithEnum()
a.someSignal.connect(lambda x: print("Signal emitted: %s" % x))


print("int(QObjectWithEnum.MyEnum.Values) =", int(QObjectWithEnum.MyEnum.Values))


The easiest way to use the wrapped library is to activate the virtual environment, which contains the correct PySide2 version, and run it

$ workon pyside2build

(pyside2build)$ python 

The expected output is:

aSlot slot called
Signal emitted: from aSlot
int(QObjectWithEnum.MyEnum.Values) = 1
nonSlotFunction returning: Some 

That’s it. Zero to Qt library bindings in one blog post. If you have any question, just leave a comment down below.

5 Responses

  1. Hi, I cannot build your example under Windows 10 64bit. My toolkits are: MSVC 2017, Qt 5.12.3 msvc 2017 64bit, Python 2.7.3 64bit. The error is: fatal error LNK1107: file invalid: cannot read at 0x320
    Could you provide me any hints?

    • Hi,

      the error you posted is unfortunately not enough information and I do not have a similar setup available at the moment to reproduce the issue. Can you paste the whole build output somewhere?

      • Hi, I have the same error on Windows, everything works fine on Linux, maybe you know what the reason could be?

        [ 44%] Linking CXX shared library libexamplebinding.dll
        LINK: command “C:\PROGRA~2\MICROS~3\2017\COMMUN~1\VC\Tools\MSVC\1416~1.270\bin\Hostx64\x64\link.exe /nologo @CMakeFiles\libexamplebinding.dir\objects1.rsp /out:libexamplebinding.dll /implib:libexamplebinding.lib /pdb:K:\project\env\pysi\pyside-setup\examples\Example_Qt\build\libexamplebinding.pdb /dll /version:0.0 /machine:x64 /INCREMENTAL:NO C:\Qt\5.12.9\msvc2017\bin\Qt5Core.dll kernel32.lib user32.lib gdi32.lib winspool.lib shell32.lib ole32.lib oleaut32.lib uuid.lib comdlg32.lib advapi32.lib /MANIFEST /MANIFESTFILE:libexamplebinding.dll.manifest” failed (exit code 1107) with the following output:
        C:\Qt\5.12.9\msvc2017\bin\Qt5Core.dll : fatal error LNK1107: invalid or corrupt file: cannot read at 0x2D8

Leave a Reply

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

Sumedha Widyadharma

Sumedha Widyadharma

Sumedha Widyadharma is a senior software developer and consultant for basysKom GmbH, creating software solutions for and with customers, usually based on Qt. He joined basysKom in 2011 as a system integrator, bringing customers solutions to life on their embedded Linux platforms. These roots are still visible as a special interest in software development practices which help increase ease of development and product quality, such as automated testing, continuous integration/deployment and development tooling.
Share on facebook
Share on twitter
Share on linkedin
Share on reddit
Share on xing
Share on email
Share on stumbleupon
Share on whatsapp
Share on pocket

Read more

IoT Cloud
Heike Ziegler
IoT: Getting started with cloud and modern IoT and IIoT from scratch

IoT and IIoT applications are special compared to other kinds of cloud applications as they have to deal with devices existing “outside” of data centers.

The following series of articles provide an end-to-end overview of what Microsoft Azure offers to handle some of the challenges involved in connecting an IoT Device with the Cloud.

By working through this series you will learn about the major concepts involved in getting your IoT/IIoT device connected to Microsoft Azure. In our examples we will feature Qt, Node.Js, Protobuf from Google and much more to get you started.

Read More »
Jeremias Bosch
Awesome :-) The basysKom Toolbox

We would like to introduce our basysKom Toolbox to you. It is a state-of-the-art collection of best practices in agile management and software development and a valuable tool for every kickoff meeting.

Come and visit us on the Embedded World 2020 and take your own copy of the printed card deck with you!

Read More »