8000 Merge pull request #7022 from jenshnielsen/improvecondaenvdocs · timhoffm/matplotlib@b0a45c4 · GitHub
[go: up one dir, main page]
Skip to content

Commit b0a45c4

Browse files
tacaswelltacaswell
authored
Merge pull request matplotlib#7022 from jenshnielsen/improvecondaenvdocs
DOC: Improve virtualenv and framework builds
2 parents 0f3dbc4 + 00f7ab5 commit b0a45c4

File tree

4 files changed

+139
-97
lines changed

4 files changed

+139
-97
lines changed

‎doc/faq/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,4 @@ The Matplotlib FAQ
2020
troubleshooting_faq.rst
2121
environment_variables_faq.rst
2222
virtualenv_faq.rst
23+
osx_framework.rst

‎doc/faq/osx_framework.rst

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
.. _osxframework-faq:
2+
3+
******************************
4+
Working with Matplotlib on OSX
5+
******************************
6+
7+
.. contents::
8+
:backlinks: none
9+
10+
11+
.. _osxframework_introduction:
12+
13+
Introduction
14+
============
15+
16+
On OSX, two different types of Python Builds exist: a regular build and a
17+
framework build. In order to interact correctly with OSX through the native
18+
GUI frameworks you need a framework build of Python.
19+
At the time of writing the ``macosx`` and ``WXAgg`` backends require a
20+
framework build to function correctly. This can result in issues for
21+
a python installation not build as a framework and may also happen in
22+
virtual envs and when using (Ana)Conda.
23+
From Matplotlib 1.5 onwards the ``macosx`` backend
24+
checks that a framework build is available and fails if a non framework
25+
build is found. WX has a similar check build in.
26+
27+
Without this check a partially functional figure is created.
28+
Among the issues with it is that it is produced in the background and
29+
cannot be put in front of any other window. Several solutions and work
30+
arounds exist see below.
31+
32+
Short version
33+
=============
34+
35+
VirtualEnv
36+
----------
37+
38+
If you are on Python 3, use
39+
`venv <https://docs.python.org/3/library/venv.html>`_
40+
instead of `virtualenv <https://virtualenv.pypa.io/en/latest/>`_::
41+
42+
python -m venv my-virtualenv
43+
source my-virtualenv/bin/activate
44+
45+
Otherwise you will need one of the workarounds below.
46+
47+
Conda
48+
-----
49+
50+
The default python provided in (Ana)Conda is not a framework
51+
build. However, the Conda developers have made it easy to install
52+
a framework build in both the main environment and in Conda envs.
53+
To use this install python.app ``conda install python.app`` and
54+
use ``pythonw`` rather than ``python``
55+
56+
57+
Long version
58+
============
59+
60+
Unfortunately virtualenv creates a non
61+
framework build even if created from a framework build of Python.
62+
As documented above you can use venv as an alternative on Python 3.
63+
64+
The issue has been reported on the virtualenv bug tracker `here
65+
<https://github.com/pypa/virtualenv/issues/54>`__ and `here
66+
<https://github.com/pypa/virtualenv/issues/609>`__
67+
68+
Until this is fixed, one of the following workarounds can be used:
69+
70+
``PYTHONHOME`` Function
71+
-----------------------
72+
73+
The best known work around is to use the non
74+
virtualenv python along with the PYTHONHOME environment variable.
75+
This can be done by defining a function in your ``.bashrc`` using
76+
77+
.. code:: bash
78+
79+
function frameworkpython {
80+
if [[ ! -z "$VIRTUAL_ENV" ]]; then
81+
PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@"
82+
else
83+
/usr/local/bin/python "$@"
84+
fi
85+
}
86+
87+
This function can then be used in all of your virtualenvs without having to
88+
fix every single one of them.
89+
90+
With this in place you can run ``frameworkpython`` to get an interactive
91+
framework build within the virtualenv. To run a script you can do
92+
``frameworkpython test.py`` where ``test.py`` is a script that requires a
93+
framework build. To run an interactive ``IPython`` session with the framework
94+
build within the virtual environment you can do ``frameworkpython -m IPython``
95+
96+
``PYTHONHOME`` Script
97+
^^^^^^^^^^^^^^^^^^^^^
98+
99+
An alternative work around borrowed from the `WX wiki
100+
<http://wiki.wxpython.org/wxPythonVirtualenvOnMac>`_, is to use the non
101+
virtualenv python along with the PYTHONHOME environment variable. This can be
102+
implemented in a script as below. To use this modify ``PYVER`` and
103+
``PATHTOPYTHON`` and put the script in the virtualenv bin directory i.e.
104+
``PATHTOVENV/bin/frameworkpython``
105+
106+
.. code:: bash
107+
108+
#!/bin/bash
109+
110+
# what real Python executable to use
111+
PYVER=2.7
112+
PATHTOPYTHON=/usr/local/bin/
113+
PYTHON=${PATHTOPYTHON}python${PYVER}
114+
115+
# find the root of the virtualenv, it should be the parent of the dir this script is in
116+
ENV=`$PYTHON -c "import os; print(os.path.abspath(os.path.join(os.path.dirname(\"$0\"), '..')))"`
117+
118+
# now run Python with the virtualenv set as Python's HOME
119+
export PYTHONHOME=$ENV
120+
exec $PYTHON "$@"
121+
122+
With this in place you can run ``frameworkpython`` as above but will need to add this script
123+
to every virtualenv
124+
125+
PythonW Compiler
126+
^^^^^^^^^^^^^^^^
127+
128+
In addition
129+
`virtualenv-pythonw-osx <https://github.com/gldnspud/virtualenv-pythonw-osx>`_
130+
provides an alternative workaround which may be used to solve the issue.

‎doc/faq/virtualenv_faq.rst

Lines changed: 5 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ Working with Matplotlib in Virtual environments
88
:backlinks: none
99

1010

11-
.. _introduction:
11+
.. _virtualenv_introduction:
1212

1313
Introduction
1414
============
@@ -25,6 +25,9 @@ If you only use the ``IPython/Jupyter Notebook``'s ``inline`` and ``notebook``
2525
backends and non interactive backends you should not have any issues and can
2626
ignore everything below.
2727

28+
If you are using Matplotlib on OSX you may also want to consider the
29+
:ref:`OSX framework FAQ <osxframework-faq>`.
30+
2831
GUI Frameworks
2932
==============
3033

@@ -40,8 +43,7 @@ exist. Some of these are given here:
4043
* The ``TKAgg`` backend doesn't require any external dependencies and is
4144
normally always available.
4245
* The ``QT4`` framework ``PySide`` is pip installable.
43-
* The upcoming `WX Phoenix <http://wiki.wxpython.org/ProjectPhoenix>`_ toolkit
44-
is ``pip`` installable.
46+
* ``PYQT5`` is pip installable on Python 3.5.
4547

4648
Other frameworks are harder to install into a virtual environment. There are at
4749
least two possible ways to get access to these in a virtual environment.
@@ -58,95 +60,3 @@ Alternatively, you can manually symlink the GUI frameworks into the environment.
5860
I.e. to use PyQt5, you should symlink ``PyQt5`` and ``sip`` from your system
5961
site packages directory into the environment taking care that the environment
6062
and the systemwide install use the same python version.
61-
62-
OSX
63-
===
64-
65-
Short version
66-
-------------
67-
68-
If you are on Python 3, use ``venv`` instead of ``virtualenv``::
69-
70-
python -m venv my-virtualenv
71-
source my-virtualenv/bin/activate
72-
73-
Otherwise you will need one of the workarounds below.
74-
75-
Long version
76-
------------
77-
78-
On OSX, two different types of Python Builds exist: a regular build and a
79-
framework build. In order to interact correctly with OSX through some
80-
GUI frameworks you need a framework build of Python.
81-
At the time of writing the ``macosx``, ``WX`` and ``WXAgg`` backends require a
82-
framework build to function correctly. Unfortunately virtualenv creates a non
83-
framework build even if created from a framework build of Python. Conda
84-
environments are framework builds. From
85-
Matplotlib 1.5 onwards the ``macosx`` backend checks that a framework build is
86-
available and fails if a non framework build is found.
87-
WX has a similar check build in.
88-
89-
The issue has been reported on the virtualenv bug tracker `here
90-
<https://github.com/pypa/virtualenv/issues/54>`__ and `here
91-
<https://github.com/pypa/virtualenv/issues/609>`__
92-
93-
Until this is fixed, one of the following workarounds must be used:
94-
95-
``PYTHONHOME`` Script
96-
^^^^^^^^^^^^^^^^^^^^^
97-
98-
The best known workaround,
99-
borrowed from the `WX wiki
100-
<http://wiki.wxpython.org/wxPythonVirtualenvOnMac>`_, is to use the non
101-
virtualenv python along with the PYTHONHOME environment variable. This can be
102-
implemented in a script as below. To use this modify ``PYVER`` and
103-
``PATHTOPYTHON`` and put the script in the virtualenv bin directory i.e.
104-
``PATHTOVENV/bin/frameworkpython``
105-
106-
.. code:: bash
107-
108-
#!/bin/bash
109-
110-
# what real Python executable to use
111-
PYVER=2.7
112-
PATHTOPYTHON=/usr/local/bin/
113-
PYTHON=${PATHTOPYTHON}python${PYVER}
114-
115-
# find the root of the virtualenv, it should be the parent of the dir this script is in
116-
ENV=`$PYTHON -c "import os; print(os.path.abspath(os.path.join(os.path.dirname(\"$0\"), '..')))"`
117-
118-
# now run Python with the virtualenv set as Python's HOME
119-
export PYTHONHOME=$ENV
120-
exec $PYTHON "$@"
121-
122-
123-
With this in place you can run ``frameworkpython`` to get an interactive
124-
framework build within the virtualenv. To run a script you can do
125-
``frameworkpython test.py`` where ``test.py`` is a script that requires a
126-
framework build. To run an interactive ``IPython`` session with the framework
127-
build within the virtual environment you can do ``frameworkpython -m IPython``
128-
129-
``PYTHONHOME`` Function
130-
^^^^^^^^^^^^^^^^^^^^^^^
131-
132-
Alternatively you can define a function in your ``.bashrc`` using
133-
134-
.. code:: bash
135-
136-
function frameworkpython {
137-
if [[ ! -z "$VIRTUAL_ENV" ]]; then
138-
PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@"
139-
else
140-
/usr/local/bin/python "$@"
141-
fi
142-
}
143-
144-
This function can then be used in all of your virtualenvs without having to
145-
fix every single one of them.
146-
147-
PythonW Compiler
148-
^^^^^^^^^^^^^^^^
149-
150-
In addition
151-
`virtualenv-pythonw-osx <https://github.com/gldnspud/virtualenv-pythonw-osx>`_
152-
provides an alternative workaround which may be used to solve the issue.

‎src/_macosx.m

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3092,8 +3092,9 @@ static bool verify_framework(void)
30923092
"framework. See the Python documentation for more information on "
30933093
"installing Python as a framework on Mac OS X. Please either reinstall "
30943094
"Python as a framework, or try one of the other backends. If you are "
3095-
"Working with Matplotlib in a virtual enviroment see 'Working with "
3096-
"Matplotlib in Virtual environments' in the Matplotlib FAQ");
3095+
"using (Ana)Conda please install python.app and replace the use of 'python' "
3096+
"with 'pythonw'. See 'Working with Matplotlib on OSX' "
3097+
"in the Matplotlib FAQ for more information.");
30973098
return false;
30983099
}
30993100

0 commit comments

Comments
 (0)
0