Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit b0a45c4

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

File tree

Expand file treeCollapse file tree

4 files changed

+139
-97
lines changed
Filter options
Expand file treeCollapse file tree

4 files changed

+139
-97
lines changed

‎doc/faq/index.rst

Copy file name to clipboardExpand all lines: doc/faq/index.rst
+1Lines 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

Copy file name to clipboard
+130Lines 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

Copy file name to clipboardExpand all lines: doc/faq/virtualenv_faq.rst
+5-95Lines 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

Copy file name to clipboardExpand all lines: src/_macosx.m
+3-2Lines 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)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.