<divid="unreleased-message"> You are reading an old version of the documentation (v1.5.1). For the latest version see <ahref="/stable/">https://matplotlib.org/stable/</a></div>
<spanid="virtualenv-faq"></span><h1>Working with Matplotlib in Virtual environments<aclass="headerlink" href="#working-with-matplotlib-in-virtual-environments" title="Permalink to this headline">¶</a></h1>
<divclass="contents topic" id="contents">
<pclass="topic-title first">Contents</p>
<ulclass="simple">
<li><aclass="reference internal" href="#working-with-matplotlib-in-virtual-environments" id="id2">Working with Matplotlib in Virtual environments</a><ul>
<spanid="id1"></span><h2>Introduction<aclass="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>When running <codeclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib</span></code> in a
<aclass="reference external" href="https://virtualenv.pypa.io/en/latest/">virtual environment</a> you may discover
a few issues. <codeclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib</span></code> itself has no issue with virtual environments.
However, the GUI frameworks that <codeclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib</span></code> uses for interactive
figures have some issues with virtual environments. Everything below assumes
some familiarity with the Matplotlib backends as found in <aclass="reference internal" href="usage_faq.html#what-is-a-backend"><span>What is a
backend?</span></a>.</p>
<p>If you only use the <codeclass="docutils literal"><spanclass="pre">IPython/Jupyter</span><spanclass="pre">Notebook</span></code>‘s <codeclass="docutils literal"><spanclass="pre">inline</span></code> and <codeclass="docutils literal"><spanclass="pre">notebook</span></code>
backends and non interactive backends you should not have any issues and can
ignore everything below.</p>
</div>
<divclass="section" id="gui-frameworks">
<h2>GUI Frameworks<aclass="headerlink" href="#gui-frameworks" title="Permalink to this headline">¶</a></h2>
<p>Interactive Matplotlib relies heavily on the interaction with external GUI
frameworks.</p>
<p>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:</p>
<ulclass="simple">
<li>The <codeclass="docutils literal"><spanclass="pre">TKAgg</span></code> backend doesn’t require any external dependencies and is
normally always available.</li>
<li>The <codeclass="docutils literal"><spanclass="pre">QT4</span></code> framework <codeclass="docutils literal"><spanclass="pre">PySide</span></code> is pip installable.</li>
is <codeclass="docutils literal"><spanclass="pre">pip</span></code> installable.</li>
</ul>
<p>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.</p>
<p>One often suggested solution is to use the <codeclass="docutils literal"><spanclass="pre">--system-site-packages</span></code> 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 <aclass="reference external" href="https://virtualenvwrapper.readthedocs.org/">virtualenvwrapper</a>
this can be toggled with the <codeclass="docutils literal"><spanclass="pre">toggleglobalsitepackages</span></code> command.</p>
<p>Alternatively, you can manually symlink the GUI frameworks into the environment.
I.e. to use PyQt5, you should symlink <codeclass="docutils literal"><spanclass="pre">PyQt5</span></code> and <codeclass="docutils literal"><spanclass="pre">sip</span></code> from your system
site packages directory into the environment taking care that the environment
and the systemwide install use the same python version.</p>
</div>
<divclass="section" id="osx">
<h2>OSX<aclass="headerlink" href="#osx" title="Permalink to this headline">¶</a></h2>
<p>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 <codeclass="docutils literal"><spanclass="pre">macosx</span></code>, <codeclass="docutils literal"><spanclass="pre">WX</span></code> and <codeclass="docutils literal"><spanclass="pre">WXAgg</span></code> 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 <codeclass="docutils literal"><spanclass="pre">macosx</span></code> backend checks that a framework build is
available and fails if a non framework build is found.
WX has a similar check build in.</p>
<p>The issue has been reported on the virtualenv bug tracker <aclass="reference external" href="https://github.com/pypa/virtualenv/issues/54">here</a> and <aclass="reference external" href="https://github.com/pypa/virtualenv/issues/609">here</a></p>
<p>Until this is fixed, one of the following workarounds must be used:</p>
<divclass="section" id="pythonhome-script">
<h3><codeclass="docutils literal"><spanclass="pre">PYTHONHOME</span></code> Script<aclass="headerlink" href="#pythonhome-script" title="Permalink to this headline">¶</a></h3>
<p>The best known workaround,
borrowed from the <aclass="reference external" href="http://wiki.wxpython.org/wxPythonVirtualenvOnMac">WX wiki</a>, 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 <codeclass="docutils literal"><spanclass="pre">PYVER</span></code> and
<codeclass="docutils literal"><spanclass="pre">PATHTOPYTHON</span></code> and put the script in the virtualenv bin directory i.e.
# now run Python with the virtualenv set as Python's HOME
export PYTHONHOME=$ENV
exec $PYTHON "$@"
</pre></div>
</div>
<p>With this in place you can run <codeclass="docutils literal"><spanclass="pre">frameworkpython</span></code> to get an interactive
framework build within the virtualenv. To run a script you can do
<codeclass="docutils literal"><spanclass="pre">frameworkpython</span><spanclass="pre">test.py</span></code> where <codeclass="docutils literal"><spanclass="pre">test.py</span></code> is a script that requires a
framework build. To run an interactive <codeclass="docutils literal"><spanclass="pre">IPython</span></code> session with the framework
build within the virtual environment you can do <codeclass="docutils literal"><spanclass="pre">frameworkpython</span><spanclass="pre">-m</span><spanclass="pre">IPython</span></code></p>
</div>
<divclass="section" id="pythonhome-function">
<h3><codeclass="docutils literal"><spanclass="pre">PYTHONHOME</span></code> Function<aclass="headerlink" href="#pythonhome-function" title="Permalink to this headline">¶</a></h3>
<p>Alternatively you can define a function in your <codeclass="docutils literal"><spanclass="pre">.bashrc</span></code> using</p>