<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<title>Working with Matplotlib in Virtual environments &mdash; Matplotlib 2.0.0 documentation</title>

<link rel="stylesheet" href="../_static/mpl.css"

type="text/css" />

<link rel="stylesheet" href="../_static/pygments.css"

type="text/css" />

<script type="text/javascript">

var DOCUMENTATION_OPTIONS = {

URL_ROOT: '../',

VERSION: '2.0.0',

COLLAPSE_INDEX: false,

FILE_SUFFIX: '.html',

HAS_SOURCE: true,

SOURCELINK_SUFFIX: '.txt'

};

</script>

<script type="text/javascript" src="../_static/jquery.js"></script>

<script type="text/javascript" src="../_static/underscore.js"></script>

<script type="text/javascript" src="../_static/doctools.js"></script>

<link rel="search" type="application/opensearchdescription+xml"

title="Search within Matplotlib 2.0.0 documentation"

href="../_static/opensearch.xml"/>

<link rel="shortcut icon" href="../_static/favicon.ico"/>

<link rel="index" title="Index" href="../genindex.html"

<link rel="search" title="Search" href="../search.html"

<link rel="top" title="Matplotlib 2.0.0 documentation" href="../index.html" />

<link rel="up" title="The Matplotlib FAQ" href="index.html" />

<link rel="next" title="Working with Matplotlib on OSX" href="osx_framework.html" />

<link rel="prev" title="Environment Variables" href="environment_variables_faq.html" />

<link rel="canonical" href="https://matplotlib.org/3.1.3/faq/virtualenv_faq.html" />

<script data-domain="matplotlib.org" defer="defer" src="https://views.scientific-python.org/js/script.js"></script>

</head>

<body>

<div id="unreleased-message"> You are reading an old version of the documentation (v2.0.0). For the latest version see <a href="/stable/">https://matplotlib.org/stable/</a> </div>

<img style="float: right; margin-bottom: -40px; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_orange_ff7600.png" usemap="#ribbonmap"/>

<map name="ribbonmap">

<area shape="poly" coords="15,0,148,-1,148,135" href="https://github.com/matplotlib/matplotlib" title="Fork me on GitHub" />

<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">

<a href="../index.html"><img src="../_static/logo2.svg" width="540px" border="0" alt="matplotlib"/></a>

<div class="related">

<h3>Navigation</h3>

<ul>

<li class="right" style="margin-right: 10px">

<a href="../genindex.html" title="General Index"

accesskey="I">index</a></li>

<li class="right" >

<a href="../py-modindex.html" title="Python Module Index"

>modules</a> |</li>

<li class="right" >

<a href="osx_framework.html" title="Working with Matplotlib on OSX"

accesskey="N">next</a> |</li>

<li class="right" >

<a href="environment_variables_faq.html" title="Environment Variables"

accesskey="P">previous</a> |</li>

<li><a href="../index.html">home</a>|&nbsp;</li>

<li><a href="../examples/index.html">examples</a>|&nbsp;</li>

<li><a href="../gallery.html">gallery</a>|&nbsp;</li>

<li><a href="../api/pyplot_summary.html">pyplot</a>|&nbsp;</li>

<li><a href="../contents.html">docs</a> &raquo;</li>

<li><a href="index.html" accesskey="U">The Matplotlib FAQ</a> &raquo;</li>

</ul>

</div>

<div class="sphinxsidebar">

<div class="sphinxsidebarwrapper">

<a href="http://depsy.org/package/python/matplotlib">

<img src="http://depsy.org/api/package/pypi/matplotlib/badge.svg">

Travis-CI: <a href="https://travis-ci.org/matplotlib/matplotlib">

<img src="https://travis-ci.org/matplotlib/matplotlib.svg?branch=master"/>

<h3><a href="../contents.html">Table Of Contents</a></h3>

<ul>

<li><a class="reference internal" href="#">Working with Matplotlib in Virtual environments</a><ul>

<li><a class="reference internal" href="#introduction">Introduction</a></li>

<li><a class="reference internal" href="#gui-frameworks">GUI Frameworks</a></li>

<div class="relations">

<h3>Related Topics</h3>

<li><a href="../contents.html">Documentation overview</a><ul>

<li><a href="index.html">The Matplotlib FAQ</a><ul>

<li>Previous: <a href="environment_variables_faq.html" title="previous chapter">Environment Variables</a></li>

<li>Next: <a href="osx_framework.html" title="next chapter">Working with Matplotlib on OSX</a></li>

</ul></li>

</ul></li>

<div role="note" aria-label="source link">

<h3>This Page</h3>

<ul class="this-page-menu">

<li><a href="../_sources/faq/virtualenv_faq.rst.txt"

rel="nofollow">Show Source</a></li>

</ul>

</div>

<div id="searchbox" style="display: none" role="search">

<h3>Quick search</h3>

<form class="search" action="../search.html" method="get">

<div><input type="text" name="q" /></div>

<div><input type="submit" value="Go" /></div>

<input type="hidden" name="check_keywords" value="yes" />

<input type="hidden" name="area" value="default" />

</form>

<script type="text/javascript">$('#searchbox').show(0);</script>

</div>

</div>

<div class="document">

<div class="documentwrapper">

<div class="bodywrapper">

<div class="body">

<div class="section" id="working-with-matplotlib-in-virtual-environments">

<span id="virtualenv-faq"></span><h1>Working with Matplotlib in Virtual environments<a class="headerlink" href="#working-with-matplotlib-in-virtual-environments" title="Permalink to this headline">¶</a></h1>

<div class="contents topic" id="contents">

<p class="topic-title first">Contents</p>

<ul class="simple">

<li><a class="reference internal" href="#working-with-matplotlib-in-virtual-environments" id="id1">Working with Matplotlib in Virtual environments</a><ul>

<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>

<li><a class="reference internal" href="#gui-frameworks" id="id3">GUI Frameworks</a></li>

<div class="section" id="introduction">

<span id="virtualenv-introduction"></span><h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>

<p>When running <code class="xref py py-mod docutils literal"><span class="pre">matplotlib</span></code> in a

<a class="reference external" href="https://virtualenv.pypa.io/en/latest/">virtual environment</a> you may discover

a few issues. <code class="xref py py-mod docutils literal"><span class="pre">matplotlib</span></code> itself has no issue with virtual environments.

However, the GUI frameworks that <code class="xref py py-mod docutils literal"><span class="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 <a class="reference internal" href="usage_faq.html#what-is-a-backend"><span class="std std-ref">What is a

backend?</span></a>.</p>

<p>If you only use the <code class="docutils literal"><span class="pre">IPython/Jupyter</span> <span class="pre">Notebook</span></code>&#8216;s <code class="docutils literal"><span class="pre">inline</span></code> and <code class="docutils literal"><span class="pre">notebook</span></code>

backends and non interactive backends you should not have any issues and can

ignore everything below.</p>

<p>If you are using Matplotlib on OSX you may also want to consider the

<a class="reference internal" href="osx_framework.html#osxframework-faq"><span class="std std-ref">OSX framework FAQ</span></a>.</p>

<div class="section" id="gui-frameworks">

<h2>GUI Frameworks<a class="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>

<ul class="simple">

<li>The <code class="docutils literal"><span class="pre">TKAgg</span></code> backend doesn&#8217;t require any external dependencies and is

normally always available.</li>

<li>The <code class="docutils literal"><span class="pre">QT4</span></code> framework <code class="docutils literal"><span class="pre">PySide</span></code> is pip installable.</li>

<li><code class="docutils literal"><span class="pre">PYQT5</span></code> is pip installable on Python 3.5.</li>

<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 <code class="docutils literal"><span class="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 <a class="reference external" href="https://virtualenvwrapper.readthedocs.io/">virtualenvwrapper</a>

this can be toggled with the <code class="docutils literal"><span class="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 <code class="docutils literal"><span class="pre">PyQt5</span></code> and <code class="docutils literal"><span class="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>

</div>

</div>

<div class="clearer"></div>

</div>

<div class="footer">

&copy; Copyright 2002 - 2012 John Hunter, Darren Dale, Eric Firing, Michael Droettboom and the Matplotlib development team; 2012 - 2016 The Matplotlib development team.

Last updated on Feb 20, 2017.

Created using <a

href="http://sphinx-doc.org/">Sphinx</a> 1.5.2.

</div>