Installing PyQt5
================

Downloading SIP
---------------

SIP must be installed before building and using PyQt5.  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 PyQt5
-----------------

You can get the latest release of the GPL version of the PyQt5 source code from
http://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 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 :file:`README` files
that relate to your platform.

If you are using the commercial version of PyQt5 then you must copy your
license file to the :file:`sip` directory.

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
:program:`configure.py` script 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:\Python33\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:

.. program:: configure.py

.. cmdoption:: --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.

.. cmdoption:: --bindir <DIR>

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

.. cmdoption:: --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
    :option:`--concatenate-split` option.

.. cmdoption:: --concatenate-split <N>

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

.. cmdoption:: --configuration <FILE>

    ``<FILE>`` contains the configuration of the PyQt5 build to be used instead
    of dynamically introspecting the system and is used when cross-compiling.
    The :file:`configurations` directory contains configuration files for a
    number of target devices.

.. cmdoption:: --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.

.. cmdoption:: --consolidate

    Normally each PyQt5 module (except for the :mod:`~PyQt5.Qt` module) is
    linked against the corresponding Qt library.  This option creates a module
    called :mod:`~PyQt5._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 PyQt5 modules.

.. cmdoption:: --dbus <DIR>

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

.. cmdoption:: --debug

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

.. cmdoption:: --designer-plugindir <DIR>

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

.. cmdoption:: --destdir <DIR>

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

.. cmdoption:: --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.

.. cmdoption:: --help, -h

    Display a help message.

.. cmdoption:: --no-designer-plugin

    The Qt Designer plugin will not be built.

.. cmdoption:: --no-docstrings

    The PyQt5 modules will not contain automatically generated docstrings.

.. cmdoption:: --no-qml-plugin

    The :program:`qmlscene` plugin will not be built.

.. cmdoption:: --no-qsci-api

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

.. cmdoption:: --no-sip-files

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

.. cmdoption:: --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.

.. cmdoption:: --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.

.. cmdoption:: --protected-not-public

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

.. cmdoption:: --pyuic5-interpreter <FILE>

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

.. cmdoption:: --qmake <FILE>

    Qt's :program:`qmake` program is used to determine how your Qt installation
    is laid out.  Normally :program:`qmake` is found on your :envvar:`PATH`.
    This option can be used to specify a particular instance of
    :program:`qmake` to use.  This option is not available on Windows where
    :program:`qmake` must be on :envvar:`PATH`.

.. cmdoption:: --qml-plugindir <DIR>

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

.. cmdoption:: --qsci-api

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

.. cmdoption:: --qsci-api-destdir <DIR>

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

.. cmdoption:: --sip <FILE>

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

.. cmdoption:: --sip-incdir <DIR>

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

.. cmdoption:: --sipdir <DIR>

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

.. cmdoption:: --spec <SPEC>

    The argument ``-spec SPEC`` will be passed to :program:`qmake`.  The
    default behaviour is platform specific.  On Windows :program:`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 :program:`configure.py` will
    try and avoid ``macx-xcode`` if possible.)

.. cmdoption:: --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.

.. cmdoption:: --trace

    The generated PyQt5 modules contain additional tracing code that is enabled
    using SIP's :func:`sip.settracemask` function.

.. cmdoption:: --vendorid

    The checking of signed Python interpreters using the `VendorID
    <http://www.riverbankcomputing.com/software/vendorid/>`__ package is
    enabled.  See also the :option:`--vendorid-incdir` and
    :option:`--vendorid-libdir` options and :ref:`ref-deploy-commercial`.

.. cmdoption:: --vendorid-incdir <DIR>

    The header file of the VendorID package can be found in the directory
    ``<DIR>``.

.. cmdoption:: --vendorid-libdir <DIR>

    The library of the VendorID package can be found in the directory
    ``<DIR>``.

.. cmdoption:: --verbose

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

.. cmdoption:: --version

    Display the PyQt5 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
:program:`qmake` ``.pro`` file created by :program:`configure.py`.


Building PyQt5
--------------

The next step is to build PyQt5 by running your platform's :program:`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.


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 versions of SIP.
