<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.1.1 documentation</title>

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

type="text/css" />

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

type="text/css" />

<link rel="stylesheet" href="../_static/gallery.css" type="text/css" />

<script type="text/javascript">

var DOCUMENTATION_OPTIONS = {

URL_ROOT: '../',

VERSION: '2.1.1',

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.1.1 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.1.1 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.1.1). For the latest version see <a href="/stable/">https://matplotlib.org/stable/</a> </div>

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

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

<div id="forkongithub"><a href="https://github.com/matplotlib/matplotlib">Fork me on GitHub</a></div>

<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="../gallery/index.html">examples</a>|&nbsp;</li>

<li><a href="../tutorials/index.html">tutorials</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="https://www.numfocus.org">

<image src="https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat&amp;colorA=E1523D&amp;colorB=007D8A">

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

<img src="../_static/depsy_badge.svg">

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

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

<br/><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>

<p>When running Matplotlib in a <a class="reference external" href="https://virtualenv.pypa.io/en/latest/">virtual environment</a> 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 <a class="reference internal" href="../tutorials/introductory/usage.html#what-is-a-backend"><span class="std std-ref">What is a backend?</span></a>.</p>

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

backends, or non-interactive backends, you should not have any issues and can

ignore everything below.</p>

<p>Likewise, the <code class="docutils literal"><span class="pre">Tk</span></code> framework (<code class="docutils literal"><span class="pre">TkAgg</span></code> backend) does not require any

external dependencies and is normally always available. On certain Linux

distributions, a package named <code class="docutils literal"><span class="pre">python-tk</span></code> (or similar) needs to be

installed.</p>

<p>Otherwise, the situation (at the time of writing) is as follows:</p>

<table border="1" class="docutils">

<col width="18%" />

<col width="36%" />

<col width="46%" />

<thead valign="bottom">

<tr class="row-odd"><th class="head">GUI framework</th>

<th class="head">pip-installable?</th>

<th class="head">conda or conda-forge-installable?</th>

<tbody valign="top">

<tr class="row-even"><td>PyQt5</td>

<td>on Python&gt;=3.5</td>

<td>yes</td>

<tr class="row-odd"><td>PyQt4</td>

<td>PySide: on Windows and OSX</td>

<td>yes</td>

<tr class="row-even"><td>PyGObject</td>

<td>no</td>

<td>on Linux</td>

<tr class="row-odd"><td>PyGTK</td>

<td>no</td>

<td>no</td>

<tr class="row-even"><td>wxPython</td>

<td>yes <a class="footnote-reference" href="#id2" id="id1">[1]</a></td>

<td>yes</td>

<table class="docutils footnote" frame="void" id="id2" rules="none">

<colgroup><col class="label" /><col /></colgroup>

<tbody valign="top">

<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>OSX and Windows wheels available on PyPI. Linux wheels available but

not on PyPI, see <a class="reference external" href="https://wxpython.org/pages/downloads/">https://wxpython.org/pages/downloads/</a>.</td></tr>

<p>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):</p>

<ul class="simple">

<li>Using <code class="docutils literal"><span class="pre">virtualenv</span></code>’s <code class="docutils literal"><span class="pre">--system-site-packages</span></code> 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

<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.</li>

<li><a class="reference external" href="https://pypi.python.org/pypi/vext">vext</a> 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. <a class="reference external" href="https://pypi.python.org/pypi/vext.pyqt5">vext.pyqt5</a>, etc.</li>

<li>The GUI frameworks can be manually symlinked into the environment, e.g. for

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 the system site-packages

into the virtualenv site-packages.</li>

<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>

</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 - 2017 The Matplotlib development team.

Last updated on Dec 11, 2017.

Created using <a

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

</div>