I apologize ahead of time if this topic has already been discussed. My situation seems to vary slightly from the others such that the path to my files is different. When trying to install matplotlib on Mac OS X 10.8.5 the following error is returned:

pip install matplotlib
# lots of install details here...
/usr/X11/include/ft2build.h:56:10: fatal error: 'freetype/config/ftheader.h' file not found
#include <freetype/config/ftheader.h>
1 error generated.
error: command 'clang' failed with exit status 1
Cleaning up...
Command /usr/bin/python -c "import setuptools, tokenize;__file__='/private/tmp/pip_build_root/matplotlib/setup.py';exec(compile(getattr(tokenize, 'open', open)(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))" install --record /tmp/pip-ohMPzS-record/install-record.txt --single-version-externally-managed --compile failed with error code 1 in /private/tmp/pip_build_root/matplotlib
Storing debug log for failure in /Users/administrator/Library/Logs/pip.log

My Homebrew has the following installed:


And I am using the Mac version of Python 2.7.2 at /usr/bin/python

So I used Finder to search for ftheader.h and it's saying the file is located at:


My questions are:

  • Is matplotlib looking for ftheader.h in the wrong place?
  • If so, how do I tell it to look in the right place?
  • Or, is something else causing the problem?

Thank you!


This seems to have fixed the problem:

sudo ln -s /usr/local/include/freetype2/ /usr/include/freetype

That creates a symlink from /usr/include/freetype to /usr/local/include/freetype2/ (when you click on /usr/include/freetype you will be redirected to /usr/local/include/freetype2/). Before you create the symlink, it's best to verify that the first path is correct on your system. The second path will be created if it does not exist.

After creating the symlink, I tried sudo pip install matplotlib again and this time it successfully installed. Mucho props to this post for the idea! I will report back if something throws up an error later downstream.

It's also worth noting that a matplotlib binary exists.

  • i am having this problem as well. i think it was an upgrade to libpng that broke everything – Zach Mar 24 '14 at 23:18
  • +1 for the sym link. Had this same issue and creating the sym link allowed me to install and use matplotlib – danengle Mar 29 '14 at 23:36

I don't think changing the contents of /usr/include (as suggested in another answer, and in other similar threads) is a good idea in general; that's Apple's "property." A similar question on StackOverflow, in the context of a Homebrew installation, instead recomments linking within /usr/local/include, which is safer, but still probably not a good idea, since Homebrew maintains that.

I think a better solution is to follow the matplotlib installation instructions and use a setup.cfg file to specify the locations of resources that aren't where it expects them. To do this while letting pip manage the installation:

  1. Download the mpl source and unpack it into DIR (e.g., DIR=matplotlib-1.3.1).

  2. cd DIR, copy 'setup.cfg.template' to 'setup.cfg', and edit the directories section to look like the following (assuming you've installed freetype2 into /usr/local, e.g., via Homebrew):

    # Uncomment to override the default basedir in setupext.py.
    # This can be a single directory or a comma-delimited list of directories.
    #basedirlist = /usr
    basedirlist = /usr/local/include/freetype2/
  3. Build matplotlib in-place (but don't install it) via: python setup.py build_ext (takes about a minute on my MacBook Pro).

  4. Install with pip from within that directory: pip install . (note the dot!).

Pip will recognize it as matplotlib and index appropriately.

I already had mpl's dependencies installed when I did this, so I'm not sure whether missing some of them complicates this.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.