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

Skip to content

Commit 3586eb3

Browse files
anntzeranntzer
committed
Simplify venv docs.
Now that venv is in stdlib, we can just recommend it instead of suggesting a bunch of workarounds for virtualenv on OSX. In the general venv docs, rework the first paragraph, which was phrased a bit awkwardly; move vext above virtualenv because the former also works in venvs (which again should be preferred).
1 parent 21c4f9e commit 3586eb3

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)