Installing PyQt4 — PyQt 4.12.1 Reference Guide

# Installing PyQt4

## Downloading SIP

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

The SIP documentation can be found at http://pyqt.sourceforge.net/Docs/sip4/.

## Downloading PyQt4

You can get the latest release of the GPL version of the PyQt4 source code from http://www.riverbankcomputing.com/software/pyqt/download.

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

## Configuring PyQt4

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 PyQt4 then you must copy your license file to the `sip` directory, or to the directory specified by the `--license-dir` option of configure-ng.py.

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

In order to configure the build of PyQt4 you need to run either the configure-ng.py or the configure.py script.

configure.py is the original configuration script that uses the build system of SIP v4 (i.e. the `sip.sipconfig` module). It will be supported for the life of PyQt4.

configure-ng.py is the new configuration script that uses Qt’s qmake program to do all the heavy lifting. It has the following advantages:

- it supports cross-compilation
- it is the basis of PyQt5’s configuration script
- generated Makefiles have an uninstall target
- it will work with SIP v5 (which will have no build system).

Users are encouraged to switch to using configure-ng.py in order to ease the future transition to SIP v5 and/or PyQt5.

### Using configure-ng.py

New in version 4.10.1.

The configure-ng.py script is used to configure PyQt4 as follows:

    python configure-ng.py

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

    c:\python34\python configure-ng.py

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

The full set of command line options is:

`--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>``,` `-b``<DIR>`

  The pyuic4, pyrcc4 and pylupdate4 utilities will be installed in the directory `<DIR>`.

`--concatenate````,` `-c```

  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>``,` `-j``<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 PyQt4 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 PyQt4 license.

`--dbus``<DIR>``,` `-s``<DIR>`

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

`--debug````,` `-u```

  The PyQt4 modules will be built with debugging symbols. On Windows this requires that a debug version of Python is installed.

`--designer-plugindir``<DIR>`

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

`--destdir``<DIR>``,` `-d``<DIR>`

  The PyQt4 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>`.

`--enable``<MODULE>``,` `-e``<MODULE>`

  Normally all PyQt4 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.

`--help````,` `-h```

  Display a help message.

`--license-dir``<DIR>`

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

`--no-deprecated```

  All Qt v4 features that have been deprecated in Qt v5 will be disabled. This is useful when porting PyQt4 applications to PyQt5.

`--no-designer-plugin```

  The Qt Designer plugin will not be built.

`--no-docstrings```

  The PyQt4 modules will not contain automatically generated docstrings.

`--no-python-dbus```

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

`--no-qsci-api```

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

`--no-sip-files```

  The `.sip` files for the PyQt4 modules will not be installed.

`--no-stubs```

  New in version 4.12.

  The PEP 484 type hint stub files for the PyQt4 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 4.11.

  The `pyuic4`, `pyrcc4` and `pylupdate4` tools will not be built.

`--no-timestamp````,` `-T```

  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.

`--plugin``<PLUGIN>``,` `-t``<PLUGIN>`

  If Qt has been built as static libraries then the static plugin `<PLUGIN>` will be linked with the appropriate PyQt4 module. The option may be specified any number of times.

`--protected-is-public```

  On certain platforms the size of PyQt4 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.

`--pyuic4-interpreter``<FILE>`

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

`--qmake``<FILE>``,` `-q``<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. This option is not available on Windows where qmake must be on `PATH`.

`--qsci-api````,` `-a```

  The `PyQt4.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>``,` `-n``<DIR>`

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

`--sip``<FILE>`

  The sip program is used to generate PyQt4’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>``,` `-v``<DIR>`

  The `.sip` files for the PyQt4 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-ng.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-ng.py will try and avoid `macx-xcode` if possible.)

`--static````,` `-k```

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

`--stubdir``<DIR>`

  New in version 4.12.

  The PEP 484 type hint stub files for the PyQt4 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 4.11.

  `<DIR>` is the name of an optional directory that replaces `sys.prefix` in the names of other directories (specifically those specifying where the various PyQt4 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 PyQt4. See Configuring with Configuration Files.

`--target-py-version``<VERSION>`

  New in version 4.11.

  `<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````,` `-r```

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

`--verbose````,` `-w```

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

`--version```

  Display the PyQt4 version number.

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-ng.py.

### Using configure.py

The configure.py script is used to configure PyQt4 as follows:

    python configure.py

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

    c:\python34\python configure.py

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

The full set of command line options is:

`--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>``,` `-b``<DIR>`

  The pyuic4, pyrcc4 and pylupdate4 utilities will be installed in the directory `<DIR>`.

`--concatenate````,` `-c```

  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>``,` `-j``<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.

`--confirm-license```

  Using this confirms that you accept the terms of the PyQt4 license.

`--consolidate````,` `-g```

  Normally each PyQt4 module (except for the `Qt` module) is linked against the corresponding Qt library. This option creates a module called `_qt` which is linked against all the required Qt libraries and the other modules are stub modules that populate their module dictionaries from this one. This is useful when linking against static Qt libraries to eliminate the need to distribute the Qt libraries while minimising the memory footprint of the PyQt4 modules.

`--dbus``<DIR>``,` `-s``<DIR>`

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

`--debug````,` `-u```

  The PyQt4 modules will be built with debugging symbols. On Windows this requires that a debug version of Python is installed.

`--destdir``<DIR>``,` `-d``<DIR>`

  The PyQt4 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>`.

`--enable``<MODULE>``,` `-e``<MODULE>`

  Normally all PyQt4 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.

`--help````,` `-h```

  Display a help message.

`--no-deprecated```

  All Qt v4 features that have been deprecated in Qt v5 will be disabled. This is useful when porting PyQt4 applications to PyQt5.

`--no-designer-plugin```

  The Qt Designer plugin will not be built.

`--no-docstrings```

  The PyQt4 modules will not contain automatically generated docstrings.

`--no-qsci-api```

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

`--no-sip-files```

  The `.sip` files for the PyQt4 modules will not be installed.

`--no-timestamp````,` `-T```

  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.

`--plugin``<PLUGIN>``,` `-t``<PLUGIN>`

  If Qt has been built as static libraries then the static plugin `<PLUGIN>` will be linked with the appropriate PyQt4 module. The option may be specified any number of times.

`--plugin-destdir``<DIR>``,` `-p``<DIR>`

  The Qt Designer plugin that manages plugins implemented in Python will be installed in the `designer` subdirectory of the directory `<DIR>`.

`--protected-is-public```

  On certain platforms the size of PyQt4 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.

`--qmake``<FILE>``,` `-q``<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. This option is not available on Windows.

`--qsci-api````,` `-a```

  The `PyQt4.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>``,` `-n``<DIR>`

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

`--sipdir``<DIR>``,` `-v``<DIR>`

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

`--static````,` `-k```

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

`--trace````,` `-r```

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

`--use-arch``<ARCH>`

  When pyuic4 calls the Python interpreter on MacOS it will be run using the architecture `<ARCH>`. See the section Configuring SIP and PyQt4 for MacOS.

`--verbose````,` `-w```

  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 PyQt4 version number.

### Configuring SIP and PyQt4 for MacOS

Note that this section only applies if you are using the configure.py script to configure PyQt4. The configure-ng.py script leaves it to Qt’s qmake program to handle the details. configure-ng.py does not support the creation of universal binaries.

Building applications for MacOS can be a complex process. Typically the following need to be taken into account:

- the architectures (i.e. i386, x86_64, ppc) that you want to support
- the earliest version of MacOS you want to support (i.e. the deployment target)
- the version of the SDK you want to use.

If you are using a binary installer for Python and/or Qt then you also need to consider how they have been built regarding the above, and what bugs they have.

SIP’s and PyQt4’s configure.py scripts provide the necessary command line options to allow the correct configurations to be specified - the trick is to work out which options to use depending on the versions of Python and Qt you have installed.

SIP provides the following command line options to its configure.py script.

- `--arch <ARCH>` specifies the target architecture and may be specified a number of times.
- `--universal` is a shortcut for `--arch i386 --arch ppc`.
- `--deployment-target <VERSION>` specifies the earliest version of MacOS you want to support. This sets the `MACOSX_DEPLOYMENT_TARGET` environment variable and should be used rather than setting the environment variable in the shell (to work around bugs in some versions of Python).
- `--sdk <SDK>` specifies the SDK to use.

PyQt4 provides the `--use-arch` option that specifies which architecture certain PyQt4 tools (actually only pyuic4 at the moment) will use when running Python. For example, if your Qt installation is 32 bits, and your Python installation is 32 bits and 64 bits then you will need to specify `--use-arch i386` to ensure that pyuic4 runs the 32 bit version of Python.

## Building PyQt4

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

    make

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

    make install

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

This will install the various PyQt4 components.

## Configuring with Configuration Files

The configure-ng.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 PyQt4 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-ng.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-ng.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/PyQt4
    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_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 PyQt4 modules will be installed. It can be overridden by the `--destdir` option.
`pyqt_modules`
  is the space separated list of PyQt4 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 PyQt4 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 PyQt4 `.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 pyuic4. It can be overridden by the `--pyuic4-interpreter` option.