diff --git a/doc/faq/index.rst b/doc/faq/index.rst index 4d2a511ecea1..492491efca52 100644 --- a/doc/faq/index.rst +++ b/doc/faq/index.rst @@ -20,3 +20,4 @@ The Matplotlib FAQ troubleshooting_faq.rst environment_variables_faq.rst virtualenv_faq.rst + osx_framework.rst diff --git a/doc/faq/osx_framework.rst b/doc/faq/osx_framework.rst new file mode 100644 index 000000000000..9953f1349768 --- /dev/null +++ b/doc/faq/osx_framework.rst @@ -0,0 +1,130 @@ +.. _osxframework-faq: + +****************************** +Working with Matplotlib on OSX +****************************** + +.. contents:: + :backlinks: none + + +.. _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 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 Matplotlib 1.5 onwards the ``macosx`` backend +checks that a framework build is available and fails if a non framework +build is found. WX has a similar check build in. + +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. + +Short version +============= + +VirtualEnv +---------- + +If you are on Python 3, use +`venv `_ +instead of `virtualenv `_:: + + python -m venv my-virtualenv + source my-virtualenv/bin/activate + +Otherwise you will need one of the workarounds below. + +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 +`__ and `here +`__ + +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 + +.. code:: bash + + 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`` Script +^^^^^^^^^^^^^^^^^^^^^ + +An alternative work around borrowed from the `WX wiki +`_, 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`` + +.. code:: bash + + #!/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 + 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 `_ +provides an alternative workaround which may be used to solve the issue. diff --git a/doc/faq/virtualenv_faq.rst b/doc/faq/virtualenv_faq.rst index 8ec25decc15e..094c3ca3432e 100644 --- a/doc/faq/virtualenv_faq.rst +++ b/doc/faq/virtualenv_faq.rst @@ -8,7 +8,7 @@ Working with Matplotlib in Virtual environments :backlinks: none -.. _introduction: +.. _virtualenv_introduction: Introduction ============ @@ -25,6 +25,9 @@ If you only use the ``IPython/Jupyter Notebook``'s ``inline`` and ``notebook`` backends and non interactive backends you should not have any issues and can ignore everything below. +If you are using Matplotlib on OSX you may also want to consider the +:ref:`OSX framework FAQ `. + GUI Frameworks ============== @@ -40,8 +43,7 @@ exist. Some of these are given here: * The ``TKAgg`` backend doesn't require any external dependencies and is normally always available. * The ``QT4`` framework ``PySide`` is pip installable. -* The upcoming `WX Phoenix `_ toolkit - is ``pip`` installable. +* ``PYQT5`` is pip installable on Python 3.5. Other frameworks are harder to install into a virtual environment. There are at 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. I.e. to use PyQt5, you should symlink ``PyQt5`` and ``sip`` from your system site packages directory into the environment taking care that the environment and the systemwide install use the same python version. - -OSX -=== - -Short version -------------- - -If you are on Python 3, use ``venv`` instead of ``virtualenv``:: - - python -m venv my-virtualenv - source my-virtualenv/bin/activate - -Otherwise you will need one of the workarounds below. - -Long version ------------- - -On OSX, two different types of Python Builds exist: a regular build and a -framework build. In order to interact correctly with OSX through some -GUI frameworks you need a framework build of Python. -At the time of writing the ``macosx``, ``WX`` and ``WXAgg`` backends require a -framework build to function correctly. Unfortunately virtualenv creates a non -framework build even if created from a framework build of Python. Conda -environments are framework builds. From -Matplotlib 1.5 onwards the ``macosx`` backend checks that a framework build is -available and fails if a non framework build is found. -WX has a similar check build in. - -The issue has been reported on the virtualenv bug tracker `here -`__ and `here -`__ - -Until this is fixed, one of the following workarounds must be used: - -``PYTHONHOME`` Script -^^^^^^^^^^^^^^^^^^^^^ - -The best known workaround, -borrowed from the `WX wiki -`_, 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`` - -.. code:: bash - - #!/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 - export PYTHONHOME=$ENV - exec $PYTHON "$@" - - -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`` Function -^^^^^^^^^^^^^^^^^^^^^^^ - -Alternatively you can define a function in your ``.bashrc`` using - -.. code:: bash - - 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. - -PythonW Compiler -^^^^^^^^^^^^^^^^ - -In addition -`virtualenv-pythonw-osx `_ -provides an alternative workaround which may be used to solve the issue. diff --git a/src/_macosx.m b/src/_macosx.m index 2051aac8d646..ad0cd14acddb 100644 --- a/src/_macosx.m +++ b/src/_macosx.m @@ -3092,8 +3092,9 @@ static bool verify_framework(void) "framework. See the Python documentation for more information on " "installing Python as a framework on Mac OS X. Please either reinstall " "Python as a framework, or try one of the other backends. If you are " - "Working with Matplotlib in a virtual enviroment see 'Working with " - "Matplotlib in Virtual environments' in the Matplotlib FAQ"); + "using (Ana)Conda please install python.app and replace the use of 'python' " + "with 'pythonw'. See 'Working with Matplotlib on OSX' " + "in the Matplotlib FAQ for more information."); return false; }