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

<head>

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

<title>Working with Matplotlib on OSX &mdash; Matplotlib 3.0.2 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/graphviz.css" type="text/css" />

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

<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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>

<script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

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

title="Search within Matplotlib 3.0.2 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 3.0.2 documentation" href="../index.html" />

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

<link rel="next" title="The Matplotlib API" href="../api/index.html" />

<link rel="prev" title="Working with Matplotlib in Virtual environments" href="virtualenv_faq.html" />

<link rel="canonical" href="https://matplotlib.org/3.1.0/faq/osx_framework.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 (v3.0.2). 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">

<div style="float: left; position: absolute; width: 496px; bottom: 0; padding-bottom: 24px"><span style="float: right; color: #789; background: white">Version 3.0.2</span></div>

<img src="../_static/logo2.png" height="125px" 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="../api/index.html" title="The Matplotlib API"

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

<li class="right" >

<a href="virtualenv_faq.html" title="Working with Matplotlib in Virtual environments"

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/api_overview.html">API</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">

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

<h3>Quick search</h3>

<div class="searchformwrapper">

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

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

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

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

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

</form>

</div>

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

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

<ul>

<li><a class="reference internal" href="#">Working with Matplotlib on OSX</a><ul>

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

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

<li><a class="reference internal" href="#conda">conda</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="virtualenv_faq.html" title="previous chapter">Working with Matplotlib in Virtual environments</a></li>

<li>Next: <a href="../api/index.html" title="next chapter">The Matplotlib API</a></li>

</ul></li>

</ul></li>

<div id="sidebar-pagesource" role="note" aria-label="source link"

style="margin-top: 1.5em; padding-top: 0.1em; border-top: 1px solid #86989b">

<a href="../_sources/faq/osx_framework.rst.txt"

style="color: #c0c0c0" rel="nofollow">Show Page Source</a>

</div>

</div>

</div>

<div class="document">

<div class="documentwrapper">

<div class="bodywrapper">

<div class="body">

<div class="section" id="working-with-matplotlib-on-osx">

<span id="osxframework-faq"></span><h1>Working with Matplotlib on OSX<a class="headerlink" href="#working-with-matplotlib-on-osx" 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-on-osx" id="id2">Working with Matplotlib on OSX</a><ul>

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

<li><a class="reference internal" href="#virtualenv" id="id4">virtualenv</a></li>

<li><a class="reference internal" href="#conda" id="id5">conda</a></li>

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

<span id="osxframework-introduction"></span><h2>Introduction<a class="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 <code class="docutils literal notranslate"><span class="pre">macosx</span></code> and <code class="docutils literal notranslate"><span class="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. (Without this check a partially

functional figure is created. In particular, it is produced in the background

and cannot be put in front of any other window.)</p>

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

<h3>virtualenv<a class="headerlink" href="#virtualenv" title="Permalink to this headline">¶</a></h3>

<p>In a <a class="reference external" href="https://virtualenv.pypa.io/">virtualenv</a>, a non-framework build is used even when the environment is

created from a framework build (<a class="reference external" href="https://github.com/pypa/virtualenv/issues/54">virtualenv bug #54</a>, <a class="reference external" href="https://github.com/pypa/virtualenv/issues/609">virtualenv bug #609</a>).</p>

<p>The solution is to not use virtualenv, but instead the stdlib's <a class="reference external" href="https://docs.python.org/3/library/venv.html">venv</a>, which

provides similar functionality but without exhibiting this issue.</p>

<p>If you absolutely need to use virtualenv rather than venv, then from within

the environment you can set the <code class="docutils literal notranslate"><span class="pre">PYTHONHOME</span></code> environment variable to

<code class="docutils literal notranslate"><span class="pre">$VIRTUAL_ENV</span></code>, then invoke Python using the full path to the framework build

(typically <code class="docutils literal notranslate"><span class="pre">/usr/local/bin/python</span></code>).</p>

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

<h3>conda<a class="headerlink" href="#conda" title="Permalink to this headline">¶</a></h3>

<p>The default python provided in (Ana)conda is not a framework build. However,

a framework build can easily be installed, both in the main environment and

in conda envs: install python.app (<code class="docutils literal notranslate"><span class="pre">conda</span> <span class="pre">install</span> <span class="pre">python.app</span></code>) and use

<code class="docutils literal notranslate"><span class="pre">pythonw</span></code> rather than <code class="docutils literal notranslate"><span class="pre">python</span></code></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 - 2018 The Matplotlib development team.

<br />

Last updated on Nov 11, 2018.

Created using

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

Doc version v3.0.2-2-g91e2d00a8.

</div>