8000 Merge pull request #5179 from jenshnielsen/virtualenvdocs · matplotlib/matplotlib@0672154 · GitHub
[go: up one dir, main page]
Skip to content

Commit 0672154

Browse files
mdboommdboom
committed
Merge pull request #5179 from jenshnielsen/virtualenvdocs
Add documentation about working in virtualenvs to the Matplotlib faq
2 parents 7b4bb9e + 31aeec2 commit 0672154

File tree

3 files changed

+117
-2
lines changed

3 files changed

+117
-2
lines changed
10000

‎doc/faq/index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,4 @@ The Matplotlib FAQ
1919
howto_faq.rst
2020
troubleshooting_faq.rst
2121
environment_variables_faq.rst
22-
22+
virtualenv_faq.rst

‎doc/faq/virtualenv_faq.rst

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
.. _virtualenv-faq:
2+
3+
***********************************************
4+
Working with Matplotlib in Virtual environments
5+
***********************************************
6+
7+
.. contents::
8+
:backlinks: none
9+
10+
11+
.. _introduction:
12+
13+
Introduction
14+
============
15+
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>`.
23+
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
26+
ignore everything below.
27+
28+
GUI Frameworks
29+
==============
30+
31+
Interactive Matplotlib relies heavily on the interaction with external GUI
32+
frameworks.
33+
34+
Most GUI frameworks are not pip installable. This makes it tricky to install
35+
them within a virtual environment. This problem does not exist if you use Conda
36+
environments where you can install all Conda supported GUI frameworks directly
37+
into the environment. In regular virtualenv environment various workarounds
38+
exist. Some of these are given here:
39+
40+
* The ``TKAgg`` backend doesn't require any external dependencies and is
41+
normally always available.
42+
* The ``QT4`` framework ``PySide`` is pip installable.
43+
* The upcoming `WX Phoenix <http://wiki.wxpython.org/ProjectPhoenix>`_ toolkit
44+
is ``pip`` installable.
45+
46+
Other frameworks are harder to install into a virtual environment. There are at
47+
least two possible ways to get access to these in a virtual environment.
48+
49+
One often suggested solution is to use the ``--system-site-packages`` option
50+
to virtualenv when creating an environment. This adds all system wide packages
51+
to the virtual environment. However, this breaks the isolation between the
52+
virtual environment and the system install. Among other issues it results in
53+
hard to debug problems with system packages shadowing the environment packages.
54+
If you use `virtualenvwrapper <https://virtualenvwrapper.readthedocs.org/>`_
55+
this can be toggled with the ``toggleglobalsitepackages`` command.
56+
57+
Alternatively, you can manually symlink the GUI frameworks into the environment.
58+
I.e. to use PyQt5, you should symlink ``PyQt5`` and ``sip`` from your system
59+
site packages directory into the environment taking care that the environment
60+
and the systemwide install use the same python version.
61+
62+
OSX
63+
===
64+
65+
On OSX, two different types of Python Builds exist: a regular build and a
66+
framework build. In order to interact correctly with OSX through some
67+
GUI frameworks you need a framework build of Python.
68+
At the time of writing the ``macosx``, ``WX`` and ``WXAgg`` backends require a
69+
framework build to function correctly. Unfortunately virtualenv creates a non
70+
framework build even if created from a framework build of Python. Conda
71+
environments are framework builds. From
72+
Matplotlib 1.5 onwards the ``macosx`` backend checks that a framework build is
73+
available and fails if a non framework build is found.
74+
WX has a similar check build in.
75+
76+
The issue has been reported on the virtualenv bug tracker `here
77+
<https://github.com/pypa/virtualenv/issues/54>`__ and `here
78+
<https://github.com/pypa/virtualenv/issues/609>`__
79+
80+
Until this is fixed, a workaround is needed. The best known workaround,
81+
borrowed from the `WX wiki
82+
<http://wiki.wxpython.org/wxPythonVirtualenvOnMac>`_, is to use the non
83+
virtualenv python along with the PYTHONHOME environment variable. This can be
84+
implemented in a script as below. To use this modify ``PYVER`` and
85+
``PATHTOPYTHON`` and put the script in the virtualenv bin directory i.e.
86+
``PATHTOVENV/bin/frameworkpython``
87+
88+
.. code:: bash
89+
90+
#!/bin/bash
91+
92+
# what real Python executable to use
93+
PYVER=2.7
94+
PATHTOPYTHON=/usr/local/b 2364 in/
95+
PYTHON=${PATHTOPYTHON}python${PYVER}
96+
97+
# find the root of the virtualenv, it should be the parent of the dir this script is in
98+
ENV=`$PYTHON -c "import os; print os.path.abspath(os.path.join(os.path.dirname(\"$0\"), '..'))"`
99+
100+
# now run Python with the virtualenv set as Python's HOME
101+
export PYTHONHOME=$ENV
102+
exec $PYTHON "$@"
103+
104+
105+
With this in place you can run ``frameworkpython`` to get an interactive
106+
framework build within the virtualenv. To run a script you can do
107+
``frameworkpython test.py`` where ``test.py`` is a script that requires a
108+
framework build. To run an interactive ``IPython`` session with the framework
109+
build within the virtual environment you can do ``frameworkpython -m IPython``
110+
111+
In addition
112+
`virtualenv-pythonw-osx <https://github.com/gldnspud/virtualenv-pythonw-osx>`_
113+
provides an alternative workaround which may be used to solve the issue.

‎src/_macosx.m

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6283,7 +6283,9 @@ static bool verify_framework(void)
62836283
"not be able to function correctly if Python is not installed as a "
62846284
"framework. See the Python documentation for more information on "
62856285
"installing Python as a framework on Mac OS X. Please either reinstall "
6286-
"Python as a framework, or try one of the other backends.");
6286+
"Python as a framework, or try one of the other backends. If you are "
6287+
"Working with Matplotlib in a virtual enviroment see 'Working with "
6288+
"Matplotlib in Virtual environments' in the Matplotlib FAQ");
62876289
return false;
62886290
}
62896291

0 commit comments

Comments
 (0)
0