@@ -7,56 +7,69 @@ Working with Matplotlib in Virtual environments
77.. contents ::
88 :backlinks: none
99
10-
1110.. _virtualenv_introduction :
1211
1312Introduction
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
2625ignore 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+
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