Installing PyQt5

Both the GPL and commercial versions of PyQt5 can be built from source packages or installed from binary wheels.

Installing from Wheels

Wheels are the standard Python packaging format for pure Python or binary extension modules such as PyQt5. PyQt5 wheels are specific to a particular version of Python. Only Python v3.5 and later is supported. Wheels are provide for 32- and 64-bit Windows, 64-bit OS X and 64-bit Linux. These correspond with the platforms for which The Qt Company provide binary installers.

Wheels are installed using the pip3 program that is included with current versions of Python.

Installing the GPL Version

To install the wheel for the GPL version of PyQt5, run:

pip3 install pyqt5

This will install the wheel for your platform and your version of Python (assuming both are supported). The wheel will be automatically downloaded from the Python Package Index.

If you get an error message saying that no downloads could be found that satisfy the rquirement then you are probably using an unsupported version of Python.

The PyQt5 wheel includes the necessary parts of the LGPL version of Qt. There is no need to install Qt yourself.

sip is packaged as a separate wheel which will be downloaded and installed automatically.

To uninstall the GPL version, run:

pip3 uninstall pyqt5

Installing the Commercial Version

It is not possible to provide wheels for the commercial version in the same way they are provided for the GPL version:

  • the user’s license information has to be applied
  • it is not possble to distribute a copy of the commercial version of Qt.

Instead unlicensed wheels are provided which do not include a copy of Qt. The program pyqtlicense is provided which takes the unlicensed wheel, the pyqt-commercial.sip license file and the location of the Qt installation and generates a licensed wheel. The licensed wheel contains a copy of the necessary parts of Qt and can be installed using pip3.

pyqtlicense assumes that the Qt installation has been created from one of the LGPL or commercial binary installers provided by The Qt Company. It may also work with a Qt installation built from source but this is unsupported.

On Windows the binary installer for MSVC 2015 must be used.

The following describes the command line options of pyqtlicense.

-h, --help

Display a help message and exit.

-V, --version

Display the version number and exit.

--build-tag TAG

This specifies that TAG should be used as the build tag in the name of the generated wheel. If TAG is an empty string then the build tag is omitted.

--license FILE

This specifies that FILE is the license file.

--no-msvc-runtime

The unlicensed wheels for 32- and 64-bit Python includes msvcp140.dll (part of the MSVC2015 C++ runtime). This specifies that the DLL should be omitted from the licensed wheel.

--no-openssl

The unlicensed wheels for 32- and 64-bit Python includes libeay32.dll and ssleay32.dll (i.e the OpenSSL DLLs). This specifies that the DLLs should be omitted from the licensed wheel.

--openssl DIR

This specifies that the libeay32.dll and ssleay32.dll DLLs included in the unlicensed wheels for 32- and 64-bit Python should be replaced by the DLLs of the same name in the directory DIR.

--output DIR

This specifies that the licensed wheel will be written to the directory DIR.

--qt DIR

This specifies that DIR contains the LGPL or commercial Qt installation to be included in the licensed wheel. The directory is what Qt refers to as the prefix directory, i.e. the architecture specific directory containing the bin, lib etc. directories. It must be specified.

--qt-version VERSION

This specifies the 3-part version number of the Qt installation. If it is not specified then it will be extracted from the value specified by the --qt option.

--quiet

This specifies that all progress messages should be suppressed.

--wheel-qt-version VERSION

This specifies the 3-part version number of the Qt installation that the wheel was built against. If it is not specified then it will be extracted from the name of the wheel file.

--verbose

This specifies that additional progress messages should be displayed.

The remaining argument is the name of the unlicensed wheel file to license.

To uninstall the commercial version, run:

pip3 uninstall pyqt5-commercial

Building and Installing from Source

Downloading SIP

SIP must be installed before building and using PyQt5. You can get the latest release of the SIP source code from https://www.riverbankcomputing.com/software/sip/download.

The SIP installation instructions can be found at https://pyqt.sourceforge.net/Docs/sip4/installation.html.

Downloading PyQt5

You can get the latest release of the GPL version of the PyQt5 source code from https://www.riverbankcomputing.com/software/pyqt/download5.

If you are using the commercial version of PyQt5 then you should use the download instructions which were sent to you when you made your purchase. You must also download your pyqt-commercial.sip license file.

Configuring PyQt5

After unpacking the source package (either a .tar.gz or a .zip file depending on your platform) you should then check for any README files that relate to your platform.

If you are using the commercial version of PyQt5 then you must copy your pyqt-commercial.sip license file to the sip directory, or to the directory specified by the --license-dir option of configure.py.

You need to make sure your environment variables are set properly for your development environment.

In order to configure the build of PyQt5 you need to run the configure.py script as follows:

python3 configure.py

This assumes that the Python interpreter is on your path. Something like the following may be appropriate on Windows:

c:\Python36\python configure.py

If you have multiple versions of Python installed then make sure you use the interpreter for which you wish to build PyQt5 for.

The full set of command line options is:

-h, --help

Display a help message and exit.

--assume-shared

Normally Qt is checked to see if it has been built as shared libraries. Some Linux distributions configure their Qt builds to make this check unreliable. This option ignores the result of the check and assumes that Qt has been built as shared libraries.

--bindir <DIR>

The pyuic5, pyrcc5 and pylupdate5 utilities will be installed in the directory <DIR>.

--concatenate

The C++ source files for a Python module will be concatenated. This results in significantly reduced compilation times. Most, but not all, C++ compilers can handle the large files that result. See also the --concatenate-split option.

--concatenate-split <N>

If the --concatenate option is used to concatenate the C++ source files then this option determines how many files are created. The default is 1.

--configuration <FILE>

<FILE> contains the configuration of the PyQt5 build to be used instead of dynamically introspecting the system and is typically used when cross-compiling. See Configuring with Configuration Files.

--confirm-license

Using this confirms that you accept the terms of the PyQt5 license. If it is omitted then you will be asked for confirmation during configuration.

--dbus <DIR>

The dbus-python.h header file of the dbus-python package can be found in the directory <DIR>/dbus.

--debug

The PyQt5 modules will be built with debugging symbols. On Windows configure.py must be run using a debug version of Python.

--designer-plugindir <DIR>

The Python plugin for Qt Designer will be installed in the directory <DIR>.

--destdir <DIR>

The PyQt5 Python package will be installed in the directory <DIR>. The default is the Python installation’s site-packages directory. If you use this option then the PYTHONPATH environment variable must include <DIR>.

--disable <MODULE>

New in version 5.5.1.

Normally all PyQt5 modules are enabled and are built if the corresponding Qt library can be found. This option will suppress the check for <MODULE>>. The option may be specified any number of times.

--enable <MODULE>

Normally all PyQt5 modules are enabled and are built if the corresponding Qt library can be found. Using this option only those modules specifically enabled will be checked for and built. The option may be specified any number of times.

--license-dir <DIR>

The license files needed by the commercial version of PyQt5 can be found in the directory <DIR>.

New in version 5.8.

On Windows the full Python API and the limited API (as used by PyQt) are implemented in different DLLs. Normally the limited DLL is linked (unless a debug version of the Python interpreter is being used to run configure.py). This option forces the full API DLL to be linked instead.

--no-designer-plugin

The Qt Designer plugin will not be built.

--no-docstrings

The PyQt5 modules will not contain automatically generated docstrings.

--no-python-dbus

The Qt support for the standard Python DBus bindings is disabled.

--no-qml-plugin

The qmlscene plugin will not be built.

--no-qsci-api

The PyQt5.api QScintilla API file is not installed even if QScintilla does appear to be installed.

--no-sip-files

The .sip files for the PyQt5 modules will not be installed.

--no-stubs

New in version 5.6.

The PEP 484 type hint stub files for the PyQt5 modules will not be installed. This option is ignored (and the stub files are not installed) for versions of Python earlier than v3.5.

--no-tools

New in version 5.3.

The pyuic5, pyrcc5 and pylupdate5 tools will not be built.

--no-timestamp

Normally the header comments of each generated C/C++ source file includes a timestamp corresponding to when the file was generated. This option suppresses the inclusion of the timestamp.

--protected-is-public

On certain platforms the size of PyQt5 modules can be significantly reduced by redefining the C++ protected keyword as public during compilation. This option enables this behaviour and is the default on Linux and MacOS/X.

--protected-not-public

The default redefinition of protected to public during compilation on Linux and MacOS/X is disabled.

--pyuic5-interpreter <FILE>

<FILE> is the name of the Python interpreter used in the pyuic5 wrapper. The default is platform dependent.

--qmake <FILE>

Qt’s qmake program is used to determine how your Qt installation is laid out. Normally qmake is found on your PATH. This option can be used to specify a particular instance of qmake to use.

--qml-debug

New in version 5.8.

Enable the QML debugging infrastructure. This should not be enabled in a production environment.

--qml-plugindir <DIR>

The Python plugin for qmlscene will be installed in the directory <DIR>.

--qsci-api

The PyQt5.api QScintilla API file is installed even if QScintilla does not appear to be installed. This option is implied if the --qsci-api-destdir option is specified.

--qsci-api-destdir <DIR>

The QScintilla API file will be installed in the python subdirectory of the api subdirectory of the directory <DIR>.

--qtconf-prefix <DIR>

New in version 5.6.

A qt.conf file is embedded in the PyQt5.QtCore module with Prefix set to <DIR> which is assumed to be relative to the directory that the PyQt5.QtCore module will be installed in.

--sip <FILE>

The sip program is used to generate PyQt5’s C++ source code. Normally sip is found on your PATH. This option can be used to specify a particular instance of sip to use.

--sip-incdir <DIR>

The sip.h header file can be found in the directory <DIR>.

--sipdir <DIR>

The .sip files for the PyQt5 modules will be installed in the directory <DIR>.

--spec <SPEC>

The argument -spec SPEC will be passed to qmake. The default behaviour is platform specific. On Windows configure.py will choose the value that is correct for the version of Python that is being used. (However if you have built Python yourself then you may need to explicitly specify <SPEC>.) On MacOS configure.py will try and avoid macx-xcode if possible.)

--static

The PyQt5 modules will be built as static libraries. This is useful when building a custom interpreter with the PyQt5 modules built in to the interpreter.

--stubdir <DIR>

New in version 5.6.

The PEP 484 type hint stub files for the PyQt5 modules will be installed in the directory <DIR>. By default they will be stored in the same directory as the corresponding extension modules. This option is ignored (and the stub files are not installed) for versions of Python earlier than v3.5.

--sysroot <DIR>

New in version 5.3.

<DIR> is the name of an optional directory that replaces sys.prefix in the names of other directories (specifically those specifying where the various PyQt5 components will be installed and where the Python include and library directories can be found). It is typically used when cross-compiling or when building a static version of PyQt5. See Configuring with Configuration Files.

--target-py-version <VERSION>

New in version 5.3.

<VERSION> is the major and minor version (e.g. 3.4) of the version of Python being targetted. By default the version of Python being used to run the configure.py script is used. It is typically used when cross-compiling. See Configuring with Configuration Files.

--trace

The generated PyQt5 modules contain additional tracing code that is enabled using SIP’s sip.settracemask() function.

--verbose

Compiler commands and any output issued during configuration is displayed instead of being suppressed. Use this if configure.py is having problems to see what exactly is going wrong.

--version

Display the version number and exit.

Any remaining command line arguments are expected to be in the form name=value or name+=value. Such arguments are added to any qmake .pro file created by configure.py.

Building PyQt5

The next step is to build PyQt5 by running your platform’s make command. For example:

make

The final step is to install PyQt5 by running the following command:

make install

(Depending on your system you may require root or administrator privileges.)

This will install the various PyQt5 components.

Configuring with Configuration Files

The configure.py script normally introspects the Python installation of the interpreter running it in order to determine the names of the various files and directories it needs. This is fine for a native build of PyQt5 but isn’t appropriate when cross-compiling. In this case it is possible to supply a configuration file, specified using the --configuration option, which contains definitions of all the required values.

A configuration file is made up of a number of named sections each of which contains a number of configuration items. The format of a configuration file is as follows:

  • a section name is a single line with the name enclosed between [ and ]
  • a configuration item is a single line containing a name/value pair separated by =
  • values may be extended to lines immediately following if they are indented by at least one space
  • a value may include another value by embedding the name of that value enclosed between %( and )
  • comments begin with # and continue to the end of the line
  • blank lines are ignored.

Those configuration items that appear before the first section name are automatically added to all sections.

A configuration file defines a section for each version of Qt that requires a different configuration. configure.py will choose the most appropriate section according to the version of Qt you are actually using. For example, if a configuration file contains sections for Qt v5.3 and Qt v5.1 and you are using Qt v5.2.1 then the section for Qt v5.1 will be chosen.

configure.py provides the following preset values for a configuration:

py_major
is the major version number of the target Python installation.
py_minor
is the minor version number of the target Python installation.
sysroot
is the name of the system root directory. This is specified with the --sysroot option.

The following is an example configuration file:

# The target Python installation.
py_platform = linux
py_inc_dir = %(sysroot)/usr/include/python%(py_major).%(py_minor)
py_pylib_dir = %(sysroot)/usr/lib/python%(py_major).%(py_minor)/config
py_pylib_lib = python%(py_major).%(py_minor)mu

# The target PyQt installation.
pyqt_module_dir = %(sysroot)/usr/lib/python%(py_major)/dist-packages
pyqt_bin_dir = %(sysroot)/usr/bin
pyqt_sip_dir = %(sysroot)/usr/share/sip/PyQt5
pyuic_interpreter = /usr/bin/python%(py_major).%(py_minor)
pyqt_disabled_features = PyQt_Desktop_OpenGL PyQt_qreal_double

# Qt configuration common to all versions.
qt_shared = True

[Qt 5.1]
pyqt_modules = QtCore QtDBus QtDesigner QtGui QtHelp QtMultimedia
    QtMultimediaWidgets QtNetwork QtOpenGL QtPrintSupport QtQml QtQuick
    QtSensors QtSerialPort QtSql QtSvg QtTest QtWebKit QtWebKitWidgets
    QtWidgets QtXmlPatterns _QOpenGLFunctions_ES2

This example contains a section for Qt v5.1. We have defined a number of values before the start of the section as they are not specific to any particular version of Qt. Note that if you use this configuration with a version of Qt earlier than v5.1 then you will get an error.

The following values can be specified in the configuration file:

qt_shared
is set if Qt has been built as shared libraries. The default value is False.
py_platform
is the target Python platform.
py_debug
is set if a debug version of the target Python is being used.
py_inc_dir
is the target Python include directory, i.e. the directory containing the Python.h file.
py_pylib_dir
is the target Python library directory.
py_pylib_lib
is the target Python interpreter library. It should not include any platform-specific prefix or suffix.
pyqt_disabled_features
is the space separated list of features (as defined by SIP’s %Feature directive) that should be disabled.
pyqt_module_dir
is the target directory where the PyQt5 modules will be installed. It can be overridden by the --destdir option.
pyqt_modules
is the space separated list of PyQt5 modules that will be built. It can be overridden by the --enable option.
pyqt_bin_dir
is the name of the target directory where the PyQt5 related executables will be installed. It can be overridden by the --bindir option.
pyqt_sip_dir
is the name of the target directory where the PyQt5 .sip files will be installed. It can be overridden by the --sipdir option.
pyuic_interpreter
is the name of the Python interpreter (as it would be called from the target system) that will be used to run pyuic5. It can be overridden by the --pyuic5-interpreter option.

Co-existence with PyQt4

PyQt5 can be installed alongside PyQt4 using the same Python interpreter without any problems so long as they are built with the same version of SIP.