Skip to content
A high-performance map tile server powered by MBTiles files
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
assets Move error style. Aug 29, 2011
commands Default tileHost option to undefined in which case the host on the re… Jun 16, 2014
configuration_examples fix #117 Dec 3, 2013
lib avoid path.exists deprecation warning Dec 13, 2012
models windows support - refs mapbox/tilelive#40 Nov 15, 2013
servers Default tileHost option to undefined in which case the host on the re… Jun 16, 2014
templates Fixing crossdomain xml Sep 8, 2011
test Update wax tests. Jul 13, 2011
.gitignore modified gitignore Aug 30, 2012
.npmignore Add npmignore. May 20, 2011 Package and changelog for 1.0.0 Dec 21, 2011
index.js another windows fix mapping HOME->USERPROFILE Nov 15, 2013


TileStream is a high-performance map tile server powered by MBTiles.

It's like TileCache, TileStache, and other map servers in that it serves normal image files that can be used in OpenLayers, Google Maps, Modest Maps, and other Javascript APIs without much trouble - and with lots of enhancements when you use Mapbox.js.

It's not like those tile servers in that it doesn't yet generate maps, it only serves maps that are generated with TileMill. This means that it's reliably fast but not designed to serve live data.

MapBox Hosting uses the same internals as TileStream but adds many features and is a hosted service rather than an installable application.


  • MBTiles-based tile server
  • Minimal gallery view and map viewer for tiles
  • Support for MBTiles interaction using Mapbox.js


  • Node.js v0.10.x or v0.8.x

After installing Node.js you can should have the npm command.


You can use npm to install TileStream:

git clone
cd tilestream
npm install

Start TileStream:


Get options:

./index.js start --help

TileStream should now be accessible from a browser at http://localhost:8888.

Installation note: OS X

Installing Node.js via Homebrew (brew install node), the PKG installer, or nvm are all good ways to install Node.js.

Installation note: Ubuntu

If installing on ubuntu we recommend installing Node.js via the chris-lea PPA:

sudo apt-add-repository ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install nodejs nodejs-dev npm


Start TileStream:

./index.js start

Get options:

./index.js start --help

If something goes wrong during the install you can do a complete install by doing

rm -rf node_modules
npm install

Some handy options::

./index.js start --uiPort=[80] --tilePort=[80] --tiles=/usr/share/tilestream

The above example specifies custom ports for the user interface and the tile store, and also demonstrates how to specify a directory other than ~/Documents/MapBox/tiles for the mbtiles directory.

Custom configuration

If you intend to run TileStream as a server on a hostname or an IP rather than as localhost, specify that hostname when you run TileStream:

tilestream --host
tilestream --host

In these examples, you would only be able to access tilestream from or, respectively, due to security restrictions.

You can also specify the hostname TileStream should use for URLs in its responses by setting a custom tileHost value:

tilestream --tileHost
./index.js start --tileHost=""

This is useful if you want to sit your TileStream server behind a proxy (such as nginx) and restrict direct access to TileStream:

tilestream --tileHost --host
./index.js start --tileHost="" --host=""

These configuration flags can also be set using a JSON file:

./index.js start --config config.json

Where config.json is something like:

  "host": [""],
  "tileHost": "",
  "tilePort": 8888,
  "uiPort": 8888


MBTiles files should be placed in the ~/Documents/MapBox/tiles directory, which is created at first run. Each tileset can be previewed at http://localhost:8888/map/[filename] where [filename] is the name of the tileset file without the .mbtiles extension.

Tileset filenames:

  • May contain letters (lower or upper case), numbers, underscores or dashes.

  • May not contain periods, spaces, non ASCII characters or other punctuation.

      World Light.mbtiles

To see the options available for use with TileStream, run

./index.js start --help


TileStream tests use Expresso.

cd tilestream
npm install expresso
npm test


See the configuration_examples directory for configuration examples with nginx and upstart.


If you run into problems during install, such as unfound dependent versions, first try deleting the node_modules/ folder and re-run node install. It seems that some errors leave the installation in an unclean state (for example if you accidentally switched node versions during the install in the hopes of making things work!).

Build Failures

npm install may cause:

Waf: Leaving directory '/Users/sundar/Projects/tilestream/node_modules/sqlite3/build'
Build failed:
-> task failed (err #1):
{task: cxx -> statement_1.o}
-> task failed (err #1):
{task: cxx -> database_1.o}
-> task failed (err #1):
{task: cxx -> sqlite3_1.o}
npm ERR! sqlite3@2.1.1 preinstall: `node-waf clean || (exit 0); node-waf configure build`
npm ERR! `sh "-c" "node-waf clean || (exit 0); node-waf configure build"` failed with 1
npm ERR!
npm ERR! Failed at the sqlite3@2.1.1 preinstall script.

Manually installing sqlite3 via npm install sqlite3 resolved this issue. Then re-run npm install in the tilestream folder:

npm install sqlite3
npm install

If you STILL get errors when launching index.js, there may be more modules to install manually. This is the list that worked for me:

npm install sqlite3
npm install mbtiles
npm install jsdom
npm install uglify-js
npm install connect
npm install qs
npm install mime

But again, all this headache may be solved by just deleting your node_modules/ folder and re-running npm install.


You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.