Writing documentation (and keeping it up to date) is a lot of work. You can help improving it by submitting any bug you encounter, or, even better, directly patching this page on Github. Thanks!

Return to Kartograph.py Docs

Installing Kartograph.py on Mac OS X

Before installing Kartograph, please install the GDAL Complete Framework as provided by William Kyngesburye on kyngchaos.com: http://www.kyngchaos.com/software/frameworks OR use HomeBrew to install GDAL as detailed in this blog post by David Lemayian.

I recommend to install Kartograph in its own virtualenv. Otherwise you need to sudo every pip call.

Install required Python packages

Kartograph.py needs a couple of Python packages. You can install them all at once using:

pip install -r https://raw.github.com/kartograph/kartograph.py/master/requirements.txt

Alternative way if GDAL install fails

Some users reported that the install of the GDAL package fails on OSX. The way around this issue is to use the pre-compiled package included in GDAL Complete Framework, which you already installed.

You need to include their location in your PYTHONPATH environment variable. This can be done either in the activate script of your virtualenv or in your favorite shell startup file (.bashrc, .profile, etc.).

export PYTHONPATH=$PYTHONPATH:/Library/Frameworks/GDAL.framework/Versions/1.9/Python/2.7/site-packages

Then use requirements-nogdal.txt to install all required packages except GDAL.

pip install -r https://raw.github.com/kartograph/kartograph.py/master/requirements-nogdal.txt

Install Kartograph.py

Then you should be ready to install Kartograph using:

pip install https://github.com/kartograph/kartograph.py/zipball/master

Test Installation

Download the 1:50m Admin 0 Countries shapefile from Natural Earth into a newly created folder "kartograph-test" in your home folder.

mkdir ~/kartograph-test
cd ~/kartograph-test;
wget http://www.naturalearthdata.com/http//www.naturalearthdata.com/download/50m/cultural/ne_50m_admin_0_countries.zip
unzip ne_50m_admin_0_countries.zip

Create a very basic map configuration by creating a new text file named "world.json" and paste the following content into it:

   "layers": [{
       "src": "ne_50m_admin_0_countries.shp"

Then you create the map using the following command:

kartograph world.json -o world.svg

Congrats, that's it. Here's what you should see now.

resulting map

There are more tests included in the Kartograph.py repository on Github.


  • Speaking about shapely, this installation guide might help you getting it running on Mac OS.
  • During the install Python will need to compile packages, make sure that you have a working compiler on your system. Installing XCode with the Command line Utils helps.

Do you want to improve this installation instructions? Please, drop me an email.