10000 Merge pull request #10696 from anntzer/simplify-venv-docs · matplotlib/matplotlib@fc73593 · GitHub
[go: up one dir, main page]
Skip to content

Commit fc73593

Browse files
jklymakjklymak
authored
Merge pull request #10696 from anntzer/simplify-venv-docs
Simplify venv docs.
2 parents 092c703 + 3586eb3 commit fc73593

File tree

2 files changed

+44
-137
lines changed

2 files changed

+44
-137
lines changed

‎doc/faq/osx_framework.rst

Lines changed: 24 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -7,135 +7,45 @@ Working with Matplotlib on OSX
77
.. contents::
88
:backlinks: none
99

10-
.. highlight:: bash
11-
1210
.. _osxframework_introduction:
1311

1412
Introduction
1513
============
1614

1715
On OSX, two different types of Python builds exist: a regular build and a
1816
framework build. In order to interact correctly with OSX through the native
19-
GUI frameworks you need a framework build of Python. At the time of writing
17+
GUI frameworks, you need a framework build of Python. At the time of writing
2018
the ``macosx`` and ``WXAgg`` backends require a framework build to function
21-
correctly. This can result in issues for a Python installation not build as a
22-
framework and may also happen in virtual envs and when using (Ana)Conda. From
19+
correctly. This can result in issues for a Python installation not build as a
20+
framework and may also happen in virtual envs and when using (Ana)conda. From
2321
Matplotlib 1.5 onwards, both backends check that a framework build is available
24-
and fail if a non framework build is found.
25-
26-
Without this check a partially functional figure is created.
27-
Among the issues with it is that it is produced in the background and
28-
cannot be put in front of any other window. Several solutions and work
29-
arounds exist see below.
22+
and fail if a non framework build is found. (Without this check a partially
23+
functional figure is created. In particular, it is produced in the background
24+
and cannot be put in front of any other window.)
3025

31-
Short version
32-
=============
33-
34-
VirtualEnv
26+
virtualenv
3527
----------
3628

37-
If you are on Python 3, use
38-
`venv <https://docs.python.org/3/library/venv.html>`_
39-
instead of `virtualenv <https://virtualenv.pypa.io/en/latest/>`_::
40-
41-
python -m venv my-virtualenv
42-
source my-virtualenv/bin/activate
29+
In a virtualenv_, a non-framework build is used even when the environment is
30+
created from a framework build (`virtualenv bug #54`_, `virtualenv bug #609`_).
4331

44-
Otherwise you will need one of the workarounds below.
32+
The solution is to not use virtualenv, but instead the stdlib's venv_, which
33+
provides similar functionality but without exhibiting this issue.
4534

46-
Pyenv
47-
-----
48-
49-
If you are using pyenv and virtualenv you can enable your python version to be installed as a framework::
35+
If you absolutely need to use virtualenv rather than venv, then from within
36+
the environment you can set the ``PYTHONHOME`` environment variable to
37+
``$VIRTUAL_ENV``, then invoke Python using the full path to the framework build
38+
(typically ``/usr/local/bin/python``).
5039

51-
PYTHON_CONFIGURE_OPTS="--enable-framework" pyenv install x.x.x
40+
.. _virtualenv: https://virtualenv.pypa.io/
41+
.. _virtualenv bug #54: https://github.com/pypa/virtualenv/issues/54
42+
.. _virtualenv bug #609: https://github.com/pypa/virtualenv/issues/609
43+
.. _venv: https://docs.python.org/3/library/venv.html
5244

53-
Conda
45+
conda
5446
-----
5547

56-
The default python provided in (Ana)Conda is not a framework
57-
build. However, the Conda developers have made it easy to install
58-
a framework build in both the main environment and in Conda envs.
59-
To use this install python.app ``conda install python.app`` and
60-
use ``pythonw`` rather than ``python``
61-
62-
63-
Long version
64-
============
65-
66-
Unfortunately virtualenv creates a non
67-
framework build even if created from a framework build of Python.
68-
As documented above you can use venv as an alternative on Python 3.
69-
70-
The issue has been reported on the virtualenv bug tracker `here
71-
<https://github.com/pypa/virtualenv/issues/54>`__ and `here
72-
<https://github.com/pypa/virtualenv/issues/609>`__
73-
74-
Until this is fixed, one of the following workarounds can be used:
75-
76-
``PYTHONHOME`` Function
77-
-----------------------
78-
79-
The best known work around is to use the non
80-
virtualenv python along with the PYTHONHOME environment variable.
81-
This can be done by defining a function in your ``.bashrc`` using ::
82-
83-
function frameworkpython {
84-
if [[ ! -z "$VIRTUAL_ENV" ]]; then
85-
PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@"
86-
else
87-
/usr/local/bin/python "$@"
88-
fi
89-
}
90-
91-
This function can then be used in all of your virtualenvs without having to
92-
fix every single one of them.
93-
94-
With this in place you can run ``frameworkpython`` to get an interactive
95-
framework build within the virtualenv. To run a script you can do
96-
``frameworkpython test.py`` where ``test.py`` is a script that requires a
97-
framework build. To run an interactive ``IPython`` session with the framework
98-
build within the virtual environment you can do ``frameworkpython -m IPython``
99-
100-
``PYTHONHOME`` and Jupyter
101-
^^^^^^^^^^^^^^^^^^^^^^^^^^
102-
103-
This approach can be followed even if using `Jupyter <https://jupyter.org/>`_
104-
notebooks: you just need to setup a kernel with the suitable ``PYTHONHOME``
105-
definition. The `jupyter-virtualenv-osx <https://github.com/mapio/jupyter-virtualenv-osx>`_
106-
script automates the creation of such a kernel.
107-
108-
109-
``PYTHONHOME`` Script
110-
^^^^^^^^^^^^^^^^^^^^^
111-
112-
An alternative work around borrowed from the `WX wiki
113-
<https://wiki.wxpython.org/wxPythonVirtualenvOnMac>`_, is to use the non
114-
virtualenv python along with the PYTHONHOME environment variable. This can be
115-
implemented in a script as below. To use this modify ``PYVER`` and
116-
``PATHTOPYTHON`` and put the script in the virtualenv bin directory i.e.
117-
``PATHTOVENV/bin/frameworkpython`` ::
118-
119-
#!/bin/bash
120-
121-
# what real Python executable to use
122-
PYVER=2.7
123-
PATHTOPYTHON=/usr/local/bin/
124-
PYTHON=${PATHTOPYTHON}python${PYVER}
125-
126-
# find the root of the virtualenv, it should be the parent of the dir this script is in
127-
ENV=`$PYTHON -c "import os; print(os.path.abspath(os.path.join(os.path.dirname(\"$0\"), '..')))"`
128-
129-
# now run Python with the virtualenv set as Python's HOME
130-
export PYTHONHOME=$ENV
131-
exec $PYTHON "$@"
132-
133-
With this in place you can run ``frameworkpython`` as above but will need to add this script
134-
to every virtualenv
135-
136-
PythonW Compiler
137-
----------------
138-
139-
In addition
140-
`virtualenv-pythonw-osx <https://github.com/gldnspud/virtualenv-pythonw-osx>`_
141-
provides an alternative workaround which may be used to solve the issue.
48+
The default python provided in (Ana)conda is not a framework build. However,
49+
a framework build can easily be installed, both in the main environment and
50+
in conda envs: install python.app (``conda install python.app``) and use
51+
``pythonw`` rather than ``python``

‎doc/faq/virtualenv_faq.rst

Lines changed: 20 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,11 @@
44
Working with Matplotlib in Virtual environments
55
***********************************************
66

7-
When running Matplotlib in a `virtual environment
8-
<https://virtualenv.pypa.io/en/latest/>`_ you may discover a few issues.
9-
Matplotlib itself has no issue with virtual environments. However, some of
10-
the external GUI frameworks that Matplotlib uses for interactive figures may
11-
be tricky to install in a virtual environment. Everything below assumes some
12-
familiarity with the Matplotlib backends as found in :ref:`What is a backend?
13-
<what-is-a-backend>`.
7+
While Matplotlib itself runs fine in a `virtual environment
8+
<https://docs.python.org/3/library/venv.html>`_ (venv), some of the GUI
9+
frameworks that Matplotlib uses for interactive figures are tricky to install
10+
in a venv. Everything below assumes some familiarity with the Matplotlib
11+
backends as found in :ref:`What is a backend? <what-is-a-backend>`.
1412

1513
If you only use the IPython and Jupyter Notebook's ``inline`` and ``notebook``
1614
backends, or non-interactive backends, you should not have any issues and can
@@ -26,33 +24,23 @@ Otherwise, the situation (at the time of writing) is as follows:
2624
============= ========================== =================================
2725
GUI framework pip-installable? conda or conda-forge-installable?
2826
============= ========================== =================================
29-
PyQt5 on Python>=3.5 yes
27+
PyQt5 yes yes
3028
------------- -------------------------- ---------------------------------
3129
PyQt4 PySide: on Windows and OSX yes
3230
------------- -------------------------- ---------------------------------
3331
PyGObject no on Linux
3432
------------- -------------------------- ---------------------------------
35-
PyGTK no no
36-
------------- -------------------------- ---------------------------------
3733
wxPython yes [#]_ yes
3834
============= ========================== =================================
3935

4036
.. [#] OSX and Windows wheels available on PyPI. Linux wheels available but
4137
not on PyPI, see https://wxpython.org/pages/downloads/.
4238
43-
In other cases, you need to install the package in the global (system)
44-
site-packages, and somehow make it available from within the virtual
45-
environment. This can be achieved by any of the following methods (in all
46-
cases, the system-wide Python and the virtualenv Python must be of the same
47-
version):
48-
49-
- Using ``virtualenv``\'s ``--system-site-packages`` option when creating
50-
an environment adds all system-wide packages to the virtual environment.
51-
However, this breaks the isolation between the virtual environment and the
52-
system install. Among other issues it results in hard to debug problems
53-
with system packages shadowing the environment packages. If you use
54-
`virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/>`_, this can be
55-
toggled with the ``toggleglobalsitepackages`` command.
39+
For cases where the framework is not installable in a venv, it needs to be
40+
install the package in the global (system) site-packages, and then made
41+
available from within the venv. This can be achieved by either of the
42+
following methods (in all cases, the system-wide Python and the venv Python
43+
must be of the same version):
5644

5745
- `vext <https://pypi.python.org/pypi/vext>`_ allows controlled access
5846
from within the virtualenv to specific system-wide packages without the
@@ -61,5 +49,14 @@ version):
6149
It is recommended to use ``vext>=0.7.0`` as earlier versions misconfigure the
6250
logging system.
6351

52+
- When using `virtualenv <https://virtualenv.pypa.io/>` (rather than the
53+
stdlib's ``venv``), using the ``--system-site-packages`` option when creating
54+
an environment adds all system-wide packages to the virtual environment.
55+
However, this breaks the isolation between the virtual environment and the
56+
system install. Among other issues it results in hard to debug problems
57+
with system packages shadowing the environment packages. If you use
58+
`virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/>`_, this can be
59+
toggled with the ``toggleglobalsitepackages`` command.
60+
6461
If you are using Matplotlib on OSX, you may also want to consider the
6562
:ref:`OSX framework FAQ <osxframework-faq>`.

0 commit comments

Comments
 (0)
0