You are reading documentation for the unreleased version of Matplotlib. Try searching for the released version of this page instead?
Applications are open for the 2018 John Hunter Matplotlib Summer Fellowship. Apply now!
Version 2.2.2.post1758+gbc39b1c4a
Fork me on GitHub

Table Of Contents

Working with Matplotlib on OSX


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 macosx and WXAgg 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.)


In a virtualenv, a non-framework build is used even when the environment is created from a framework build (virtualenv bug #54, virtualenv bug #609).

The solution is to not use virtualenv, but instead the stdlib's venv, which provides similar functionality but without exhibiting this issue.

If you absolutely need to use virtualenv rather than venv, then from within the environment you can set the PYTHONHOME environment variable to $VIRTUAL_ENV, then invoke Python using the full path to the framework build (typically /usr/local/bin/python).


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 (conda install and use pythonw rather than python