8000 Simplify venv docs. by anntzer · Pull Request #10696 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

Simplify venv docs. #10696

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Mar 16, 2018
Merged

Simplify venv docs. #10696

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed 8000 to load files.
Loading
Diff view
Diff view
138 changes: 24 additions & 114 deletions doc/faq/osx_framework.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,135 +7,45 @@ Working with Matplotlib on OSX
.. contents::
:backlinks: none

.. highlight:: bash

.. _osxframework_introduction:

Introduction
============

On OSX, two different types of Python builds exist: a regular build and a
framework build. In order to interact correctly with OSX through the native
GUI frameworks you need a framework build of Python. At the time of writing
GUI frameworks, you need a framework build of Python. At the time of writing
the ``macosx`` and ``WXAgg`` backends require a framework build to function
correctly. This can result in issues for a Python installation not build as a
framework and may also happen in virtual envs and when using (Ana)Conda. From
correctly. This can result in issues for a Python installation not build as a
framework and may also happen in virtual envs and when using (Ana)conda. From
Matplotlib 1.5 onwards, both backends check that a framework build is available
and fail if a non framework build is found.

Without this check a partially functional figure is created.
Among the issues with it is that it is produced in the background and
cannot be put in front of any other window. Several solutions and work
arounds exist see below.
and fail if a non framework build is found. (Without this check a partially
functional figure is created. In particular, it is produced in the background
and cannot be put in front of any other window.)

Short version
=============

VirtualEnv
virtualenv
----------

If you are on Python 3, use
`venv <https://docs.python.org/3/library/venv.html>`_
instead of `virtualenv <https://virtualenv.pypa.io/en/latest/>`_::

python -m venv my-virtualenv
source my-virtualenv/bin/activate
In a virtualenv_, a non-framework build is used even when the environment is
created from a framework build (`virtualenv bug #54`_, `virtualenv bug #609`_).

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

Pyenv
-----

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

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

Conda
conda
-----

The default python provided in (Ana)Conda is not a framework
build. However, the Conda developers have made it easy to install
a framework build in both the main environment and in Conda envs.
To use this install python.app ``conda install python.app`` and
use ``pythonw`` rather than ``python``


Long version
============

Unfortunately virtualenv creates a non
framework build even if created from a framework build of Python.
As documented above you can use venv as an alternative on Python 3.

The issue has been reported on the virtualenv bug tracker `here
<https://github.com/pypa/virtualenv/issues/54>`__ and `here
<https://github.com/pypa/virtualenv/issues/609>`__

Until this is fixed, one of the following workarounds can be used:

``PYTHONHOME`` Function
-----------------------

The best known work around is to use the non
virtualenv python along with the PYTHONHOME environment variable.
This can be done by defining a function in your ``.bashrc`` using ::

function frameworkpython {
if [[ ! -z "$VIRTUAL_ENV" ]]; then
PYTHONHOME=$VIRTUAL_ENV /usr/local/bin/python "$@"
else
/usr/local/bin/python "$@"
fi
}

This function can then be used in all of your virtualenvs without having to
fix every single one of them.

With this in place you can run ``frameworkpython`` to get an interactive
framework build within the virtualenv. To run a script you can do
``frameworkpython test.py`` where ``test.py`` is a script that requires a
framework build. To run an interactive ``IPython`` session with the framework
build within the virtual environment you can do ``frameworkpython -m IPython``

``PYTHONHOME`` and Jupyter
^^^^^^^^^^^^^^^^^^^^^^^^^^

This approach can be followed even if using `Jupyter <https://jupyter.org/>`_
notebooks: you just need to setup a kernel with the suitable ``PYTHONHOME``
definition. The `jupyter-virtualenv-osx <https://github.com/mapio/jupyter-virtualenv-osx>`_
script automates the creation of such a kernel.


``PYTHONHOME`` Script
^^^^^^^^^^^^^^^^^^^^^

An alternative work around borrowed from the `WX wiki
<https://wiki.wxpython.org/wxPythonVirtualenvOnMac>`_, is to use the non
virtualenv python along with the PYTHONHOME environment variable. This can be
implemented in a script as below. To use this modify ``PYVER`` and
``PATHTOPYTHON`` and put the script in the virtualenv bin directory i.e.
``PATHTOVENV/bin/frameworkpython`` ::

#!/bin/bash

# what real Python executable to use
PYVER=2.7
PATHTOPYTHON=/usr/local/bin/
PYTHON=${PATHTOPYTHON}python${PYVER}

# find the root of the virtualenv, it should be the parent of the dir this script is in
ENV=`$PYTHON -c "import os; print(os.path.abspath(os.path.join(os.path.dirname(\"$0\"), '..')))"`

# now run Python with the virtualenv set as Python's HOME
8000 export PYTHONHOME=$ENV
exec $PYTHON "$@"

With this in place you can run ``frameworkpython`` as above but will need to add this script
to every virtualenv

PythonW Compiler
----------------

In addition
`virtualenv-pythonw-osx <https://github.com/gldnspud/virtualenv-pythonw-osx>`_
provides an alternative workaround which may be used to solve the issue.
The default python provided in (Ana)conda is not a framework build. However,
a framework build can easily be installed, both in the main environment and
in conda envs: install python.app (``conda install python.app``) and use
``pythonw`` rather than ``python``
43 changes: 20 additions & 23 deletions doc/faq/virtualenv_faq.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,11 @@
Working with Matplotlib in Virtual environments
***********************************************

When running Matplotlib in a `virtual environment
<https://virtualenv.pypa.io/en/latest/>`_ you may discover a few issues.
Matplotlib itself has no issue with virtual environments. However, some of
the external GUI frameworks that Matplotlib uses for interactive figures may
be tricky to install in a virtual environment. Everything below assumes some
familiarity with the Matplotlib backends as found in :ref:`What is a backend?
< 8000 span class='blob-code-inner blob-code-marker js-skip-tagsearch' data-code-marker="-"><what-is-a-backend>`.
While Matplotlib itself runs fine in a `virtual environment
<https://docs.python.org/3/library/venv.html>`_ (venv), some of the GUI
frameworks that Matplotlib uses for interactive figures are tricky to install
in a venv. Everything below assumes some familiarity with the Matplotlib
backends as found in :ref:`What is a backend? <what-is-a-backend>`.

If you only use the IPython and Jupyter Notebook's ``inline`` and ``notebook``
backends, or non-interactive backends, you should not have any issues and can
Expand All @@ -26,33 +24,23 @@ Otherwise, the situation (at the time of writing) is as follows:
============= ========================== =================================
GUI framework pip-installable? conda or conda-forge-installable?
============= ========================== =================================
PyQt5 on Python>=3.5 yes
PyQt5 yes yes
------------- -------------------------- ---------------------------------
PyQt4 PySide: on Windows and OSX yes
------------- -------------------------- ---------------------------------
PyGObject no on Linux
------------- -------------------------- ---------------------------------
PyGTK no no
------------- -------------------------- ---------------------------------
wxPython yes [#]_ yes
============= ========================== =================================

.. [#] OSX and Windows wheels available on PyPI. Linux wheels available but
not on PyPI, see https://wxpython.org/pages/downloads/.

In other cases, you need to install the package in the global (system)
site-packages, and somehow make it available from within the virtual
environment. This can be achieved by any of the following methods (in all
cases, the system-wide Python and the virtualenv Python must be of the same
version):

- Using ``virtualenv``\'s ``--system-site-packages`` option when creating
an environment adds all system-wide packages to the virtual environment.
However, this breaks the isolation between the virtual environment and the
system install. Among other issues it results in hard to debug problems
with system packages shadowing the environment packages. If you use
`virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/>`_, this can be
toggled with the ``toggleglobalsitepackages`` command.
For cases where the framework is not installable in a venv, it needs to be
install the package in the global (system) site-packages, and then made
available from within the venv. This can be achieved by either of the
following methods (in all cases, the system-wide Python and the venv Python
must be of the same version):

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

- When using `virtualenv <https://virtualenv.pypa.io/>` (rather than the
stdlib's ``venv``), using the ``--system-site-packages`` option when creating
an environment adds all system-wide packages to the virtual environment.
However, this breaks the isolation between the virtual environment and the
system install. Among other issues it results in hard to debug problems
with system packages shadowing the environment packages. If you use
`virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/>`_, this can be
toggled with the ``toggleglobalsitepackages`` command.

If you are using Matplotlib on OSX, you may also want to consider the
:ref:`OSX framework FAQ <osxframework-faq>`.
0