<divid="unreleased-message"> You are reading an old version of the documentation (v2.2.4). For the latest version see <ahref="/stable/">https://matplotlib.org/stable/</a></div>
<spanid="osxframework-faq"></span><h1>Working with Matplotlib on OSX<aclass="headerlink" href="#working-with-matplotlib-on-osx" 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-on-osx" id="id2">Working with Matplotlib on OSX</a><ul>
<spanid="osxframework-introduction"></span><h2>Introduction<aclass="headerlink" href="#introduction" 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 the native
GUI frameworks you need a framework build of Python. At the time of writing
the <codeclass="docutils literal notranslate"><spanclass="pre">macosx</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">WXAgg</span></code> 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, both backends check that a framework build is available
and fail if a non framework build is found.</p>
<p>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.</p>
</div>
<divclass="section" id="short-version">
<h2>Short version<aclass="headerlink" href="#short-version" title="Permalink to this headline">¶</a></h2>
<divclass="section" id="virtualenv">
<h3>VirtualEnv<aclass="headerlink" href="#virtualenv" title="Permalink to this headline">¶</a></h3>
<h3>Conda<aclass="headerlink" href="#conda" title="Permalink to this headline">¶</a></h3>
<p>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 <codeclass="docutils literal notranslate"><spanclass="pre">conda</span><spanclass="pre">install</span><spanclass="pre">python.app</span></code> and
use <codeclass="docutils literal notranslate"><spanclass="pre">pythonw</span></code> rather than <codeclass="docutils literal notranslate"><spanclass="pre">python</span></code></p>
</div>
</div>
<divclass="section" id="long-version">
<h2>Long version<aclass="headerlink" href="#long-version" title="Permalink to this headline">¶</a></h2>
<p>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.</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 can be used:</p>
<divclass="section" id="pythonhome-function">
<h3><codeclass="docutils literal notranslate"><spanclass="pre">PYTHONHOME</span></code> Function<aclass="headerlink" href="#pythonhome-function" title="Permalink to this headline">¶</a></h3>
<p>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 <codeclass="docutils literal notranslate"><spanclass="pre">.bashrc</span></code> using</p>
<p>This function can then be used in all of your virtualenvs without having to
fix every single one of them.</p>
<p>With this in place you can run <codeclass="docutils literal notranslate"><spanclass="pre">frameworkpython</span></code> to get an interactive
framework build within the virtualenv. To run a script you can do
<codeclass="docutils literal notranslate"><spanclass="pre">frameworkpython</span><spanclass="pre">test.py</span></code> where <codeclass="docutils literal notranslate"><spanclass="pre">test.py</span></code> is a script that requires a
framework build. To run an interactive <codeclass="docutils literal notranslate"><spanclass="pre">IPython</span></code> session with the framework
build within the virtual environment you can do <codeclass="docutils literal notranslate"><spanclass="pre">frameworkpython</span><spanclass="pre">-m</span><spanclass="pre">IPython</span></code></p>
<divclass="section" id="pythonhome-and-jupyter">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">PYTHONHOME</span></code> and Jupyter<aclass="headerlink" href="#pythonhome-and-jupyter" title="Permalink to this headline">¶</a></h4>
<p>This approach can be followed even if using <aclass="reference external" href="https://jupyter.org/">Jupyter</a>
notebooks: you just need to setup a kernel with the suitable <codeclass="docutils literal notranslate"><spanclass="pre">PYTHONHOME</span></code>
definition. The <aclass="reference external" href="https://github.com/mapio/jupyter-virtualenv-osx">jupyter-virtualenv-osx</a>
script automates the creation of such a kernel.</p>
</div>
<divclass="section" id="pythonhome-script">
<h4><codeclass="docutils literal notranslate"><spanclass="pre">PYTHONHOME</span></code> Script<aclass="headerlink" href="#pythonhome-script" title="Permalink to this headline">¶</a></h4>
<p>An alternative work around borrowed from the <aclass="reference external" href="https://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 notranslate"><spanclass="pre">PYVER</span></code> and
<codeclass="docutils literal notranslate"><spanclass="pre">PATHTOPYTHON</span></code> and put the script in the virtualenv bin directory i.e.
<p>With this in place you can run <codeclass="docutils literal notranslate"><spanclass="pre">frameworkpython</span></code> as above but will need to add this script
to every virtualenv</p>
</div>
</div>
<divclass="section" id="pythonw-compiler">
<h3>PythonW Compiler<aclass="headerlink" href="#pythonw-compiler" title="Permalink to this headline">¶</a></h3>