Update venv faq.

The situation is much better: most GUI toolkits are now pip-installable.
matplotlib · tacaswell · Oct 7, 2017 · Sep 20, 2017 · Sep 20, 2017 · Sep 20, 2017
commit 3b52f44562e2fe606786ffcec58fc7af80bc9929
diff --git a/doc/faq/virtualenv_faq.rst b/doc/faq/virtualenv_faq.rst
@@ -7,56 +7,69 @@ Working with Matplotlib in Virtual environments
 .. contents::
   :backlinks: none

-
 .. _virtualenv_introduction:

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

-When running :mod:`matplotlib` in a
-`virtual environment <https://virtualenv.pypa.io/en/latest/>`_ you may discover
-a few issues. :mod:`matplotlib` itself has no issue with virtual environments.
-However, the GUI frameworks that :mod:`matplotlib` uses for interactive
-figures have some issues with virtual environments. Everything below assumes
-some familiarity with the Matplotlib backends as found in :ref:`What is a
-backend? <what-is-a-backend>`.
+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?
+<what-is-a-backend>`.

-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
+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
 ignore everything below.

-If you are using Matplotlib on OSX you may also want to consider the
-:ref:`OSX framework FAQ <osxframework-faq>`.
+Likewise, the ``Tk`` framework (``TkAgg`` backend) does not require any
+external dependencies and is normally always available.  On certain Linux
+distributions, a package named ``python-tk`` (or similar) needs to be
+installed.
+
+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
+------------- -------------------------- ---------------------------------
+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/.

-GUI Frameworks
-==============
-
-Interactive Matplotlib relies heavily on the interaction with external GUI
-frameworks.
-
-Most GUI frameworks are not pip installable. This makes it tricky to install
-them within a virtual environment. This problem does not exist if you use Conda
-environments where you can install all Conda supported GUI frameworks directly
-into the environment. In regular virtualenv environment various workarounds
-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.
-* ``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.
-
-One often suggested solution is to use the ``--system-site-packages`` option
-to virtualenv when creating an environment. This 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.
-
-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.
+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.
+
+- `vext <https://pypi.python.org/pypi/vext>`_ allows controlled access
+  from within the virtualenv to specific system-wide packages without the
+  overall shadowing issue.  A specific package needs to be installed for each
+  framework, e.g. `vext.pyqt5 <https://pypi.python.org/pypi/vext.pyqt5>`_, etc.
+
+- The GUI frameworks can be manually symlinked into the environment, e.g. for
+  PyQt5, you should symlink ``PyQt5`` and ``sip`` from the system site-packages
+  into the virtualenv site-packages.
+
+If you are using Matplotlib on OSX, you may also want to consider the
+:ref:`OSX framework FAQ <osxframework-faq>`.