Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 3b52f44

Browse files
anntzeranntzer
committed
Update venv faq.
The situation is much better: most GUI toolkits are now pip-installable.
1 parent 790c843 commit 3b52f44

File tree

1 file changed

+57
-44
lines changed

1 file changed

+57
-44
lines changed

‎doc/faq/virtualenv_faq.rst

Lines changed: 57 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -7,56 +7,69 @@ Working with Matplotlib in Virtual environments
77
.. contents::
88
:backlinks: none
99

10-
1110
.. _virtualenv_introduction:
1211

1312
Introduction
1413
============
1514

16-
When running :mod:`matplotlib` in a
17-
`virtual environment <https://virtualenv.pypa.io/en/latest/>`_ you may discover
18-
a few issues. :mod:`matplotlib` itself has no issue with virtual environments.
19-
However, the GUI frameworks that :mod:`matplotlib` uses for interactive
20-
figures have some issues with virtual environments. Everything below assumes
21-
some familiarity with the Matplotlib backends as found in :ref:`What is a
22-
backend? <what-is-a-backend>`.
15+
When running Matplotlib in a `virtual environment
16+
<https://virtualenv.pypa.io/en/latest/>`_ you may discover a few issues.
17+
Matplotlib itself has no issue with virtual environments. However, some of
18+
the external GUI frameworks that Matplotlib uses for interactive figures may
19+
be tricky to install in a virtual environment. Everything below assumes some
20+
familiarity with the Matplotlib backends as found in :ref:`What is a backend?
21+
<what-is-a-backend>`.
2322

24-
If you only use the ``IPython/Jupyter Notebook``'s ``inline`` and ``notebook``
25-
backends and non interactive backends you should not have any issues and can
23+
If you only use the IPython and Jupyter Notebook's ``inline`` and ``notebook``
24+
backends, or non-interactive backends, you should not have any issues and can
2625
ignore everything below.
2726

28-
If you are using Matplotlib on OSX you may also want to consider the
29-
:ref:`OSX framework FAQ <osxframework-faq>`.
27+
Likewise, the ``Tk`` framework (``TkAgg`` backend) does not require any
28+
external dependencies and is normally always available. On certain Linux
29+
distributions, a package named ``python-tk`` (or similar) needs to be
30+
installed.
31+
32+
Otherwise, the situation (at the time of writing) is as follows:
33+
34+
============= ========================== =================================
35+
GUI framework pip-installable? conda or conda-forge-installable?
36+
============= ========================== =================================
37+
PyQt5 on Python>=3.5 yes
38+
------------- -------------------------- ---------------------------------
39+
PyQt4 PySide: on Windows and OSX yes
40+
------------- -------------------------- ---------------------------------
41+
PyGObject no on Linux
42+
------------- -------------------------- ---------------------------------
43+
PyGTK no no
44+
------------- -------------------------- ---------------------------------
45+
wxPython yes [#]_ yes
46+
============= ========================== =================================
47+
48+
.. [#] OSX and Windows wheels available on PyPI. Linux wheels available but
49+
not on PyPI, see https://wxpython.org/pages/downloads/.
3050
31-
GUI Frameworks
32-
==============
33-
34-
Interactive Matplotlib relies heavily on the interaction with external GUI
35-
frameworks.
36-
37-
Most GUI frameworks are not pip installable. This makes it tricky to install
38-
them within a virtual environment. This problem does not exist if you use Conda
39-
environments where you can install all Conda supported GUI frameworks directly
40-
into the environment. In regular virtualenv environment various workarounds
41-
exist. Some of these are given here:
42-
43-
* The ``TKAgg`` backend doesn't require any external dependencies and is
44-
normally always available.
45-
* The ``QT4`` framework ``PySide`` is pip installable.
46-
* ``PYQT5`` is pip installable on Python 3.5.
47-
48-
Other frameworks are harder to install into a virtual environment. There are at
49-
least two possible ways to get access to these in a virtual environment.
50-
51-
One often suggested solution is to use the ``--system-site-packages`` option
52-
to virtualenv when creating an environment. This adds all system wide packages
53-
to the virtual environment. However, this breaks the isolation between the
54-
virtual environment and the system install. Among other issues it results in
55-
hard to debug problems with system packages shadowing the environment packages.
56-
If you use `virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/>`_
57-
this can be toggled with the ``toggleglobalsitepackages`` command.
58-
59-
Alternatively, you can manually symlink the GUI frameworks into the environment.
60-
I.e. to use PyQt5, you should symlink ``PyQt5`` and ``sip`` from your system
61-
site packages directory into the environment taking care that the environment
62-
and the systemwide install use the same python version.
51+
In other cases, you need to install the package in the global (system)
52+
site-packages, and somehow make it available from within the virtual
53+
environment. This can be achieved by any of the following methods (in all
54+
cases, the system-wide Python and the virtualenv Python must be of the same
55+
version):
56+
57+
- Using ``virtualenv``\'s ``--system-site-packages`` option when creating
58+
an environment adds all system-wide packages to the virtual environment.
59+
However, this breaks the isolation between the virtual environment and the
60+
system install. Among other issues it results in hard to debug problems
61+
with system packages shadowing the environment packages. If you use
62+
`virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/>`_, this can be
63+
toggled with the ``toggleglobalsitepackages`` command.
64+
65+
- `vext <https://pypi.python.org/pypi/vext>`_ allows controlled access
66+
from within the virtualenv to specific system-wide packages without the
67+
overall shadowing issue. A specific package needs to be installed for each
68+
framework, e.g. `vext.pyqt5 <https://pypi.python.org/pypi/vext.pyqt5>`_, etc.
69+
70+
- The GUI frameworks can be manually symlinked into the environment, e.g. for
71+
PyQt5, you should symlink ``PyQt5`` and ``sip`` from the system site-packages
72+
into the virtualenv site-packages.
73+
74+
If you are using Matplotlib on OSX, you may also want to consider the
75+
:ref:`OSX framework FAQ <osxframework-faq>`.

0 commit comments

Comments
 (0)