Skip to content
This repository

A stylish alternative for caching your map tiles.

Merge pull request #163 from riordan/documentation-linkfix

Links to PIL documentation for image settings are broken
latest commit 0cc0f3cff0
migurski authored
Octocat-spinner-32 TileStache Updated documentation to accurate link for additional PIL image confi… November 04, 2013
Octocat-spinner-32 examples Correction to example config for Composite provider May 09, 2012
Octocat-spinner-32 man fix minus signs in tilestache-clean manpage September 23, 2012
Octocat-spinner-32 scripts Backing out most uses of incompatible getTile signature introduced in f… May 26, 2013
Octocat-spinner-32 tests Updated most JSON mime-types from text/json to application/json, closes June 23, 2013
Octocat-spinner-32 www Added more collaborators to home page April 20, 2013
Octocat-spinner-32 .gitignore Ignore Coverage and Intellij files February 03, 2013
Octocat-spinner-32 .travis.yml Cleaned up details in vectiles tests June 20, 2013
Octocat-spinner-32 API.html Updated documentation to accurate link for additional PIL image confi… November 04, 2013
Octocat-spinner-32 CHANGELOG Bumped to 1.49.8 with numerous internal bug fixes July 02, 2013
Octocat-spinner-32 LICENSE Committed to BSD license November 15, 2010
Octocat-spinner-32 Makefile Bumped to 1.49.5 with tweaked VecTiles Provider documentation June 20, 2013
Octocat-spinner-32 Oops, need to use our own build status thingie February 05, 2013
Octocat-spinner-32 VERSION Bumped to 1.49.8 with numerous internal bug fixes July 02, 2013
Octocat-spinner-32 requirements.txt Add Vector Provider Tests February 26, 2013
Octocat-spinner-32 add script to run nose tests February 04, 2013
Octocat-spinner-32 Add Werkzeug dependency May 26, 2013
Octocat-spinner-32 tilestache.cfg Added sample OSM palette to illustrate 8-bit PNGs July 15, 2011
Octocat-spinner-32 tilestache.cgi Introduced a full set of path possibilities to Disk cache configuration April 24, 2010


a stylish alternative for caching your map tiles

Build Status

TileStache is a Python-based server application that can serve up map tiles based on rendered geographic data. You might be familiar with TileCache, the venerable open source WMS server from MetaCarta. TileStache is similar, but we hope simpler and better-suited to the needs of designers and cartographers.


import TileStache
import ModestMaps

config = {
  "cache": {"name": "Test"},
  "layers": {
    "example": {
        "provider": {"name": "mapnik", "mapfile": "examples/style.xml"},
        "projection": "spherical mercator"

# like
coord = ModestMaps.Core.Coordinate(0, 0, 1)
config = TileStache.Config.buildConfiguration(config)
type, bytes = TileStache.getTile(config.layers['example'], coord, 'png')

open('tile.png', 'w').write(bytes)




Install the pure python modules with pip:

sudo pip install -U PIL modestmaps simplejson werkzeug

Install pip ( like:

curl -O
sudo python

Install Mapnik via instructions at:


TileStache can be run from the download directory as is. For example the scripts:

Can all be run locally like:


To install globally do:

python install
  • Note: you may need to prefix that command with 'sudo' to have permissions to fully install TileStache.


To make sure TileStache is working start the development server:


Then open a modern web browser and you should be able to preview tiles at:


This is a previewer that uses ModestMaps and OpenStreetMap tiles from as defined in the default config file 'tilestache.cfg'


The next step is to learn how build custom layers and serve them.

See the docs for details.


Rendering providers:

  • Mapnik
  • Proxy
  • Vector
  • Templated URLs

Caching backends:

  • Local disk
  • Test
  • Memcache
  • S3

Design Goals

The design of TileStache focuses on approachability at the expense of cleverness or completeness. Our hope is to make it easy for anyone to design a new map of their city, publish a fresh view of their world, or even build the next 8-Bit NYC (

  • Small

The core of TileStache is intended to have a small code footprint. It should be quick and easy to to understand what the library is doing and why, based on common entry points like included CGI scripts. Where possible, dynamic programming "magic" is to be avoided, in favor of basic, procedural and copiously-documented Python.

  • Pluggable

We want to accept plug-ins and extensions from outside TileStache, and offer TileStache itself as an extension for other systems. It must be possible to write and use additional caches or renderers without having to modify the core package itself, extend classes from inside the package, or navigate chains of class dependencies. Duck typing and stable interfaces win.

  • Sensible Defaults

The default action of a configured TileStache instance should permit the most common form of interaction: a worldwide, spherical-mercator upper-left oriented tile layout compatible with those used by OpenStreetMap, Google, Bing Maps, Yahoo! and others. It should be possible to make TileStache do whatever is necessary to support any external system, but we eschew complex, impenetrable standards in favor of pragmatic, fast utility with basic web clients.


BSD, see LICENSE file.

Something went wrong with that request. Please try again.