# OSM Bright is a CartoCSS map template for OpenStreetMap data > OSM Bright is a styling template, written in the Carto language and meant to be opened as a project in TileMill, that turns an OpenStreetMap database into a map you can then edit. Getting it running means a specific chain of shapefiles, PostGIS, an import tool and a configure file, and the whole chain is tied to the older TileMill workflow. **mapbox/osm-bright** — A Carto template for OpenStreetMap data - Repository: https://github.com/mapbox/osm-bright - Stars: 703 · Forks: 221 - Language: CartoCSS - License: BSD-3-Clause - Published: 2026-10-21 · Updated: 2026-10-21 · Language: en - Canonical page: https://hysenlabs.com/projects/mapbox-osm-bright ## A template, not a renderer OSM Bright is described as a sensible starting point for quickly making beautiful maps based on an OpenStreetMap database, and it is written in the Carto styling language and can be opened as a project in TileMill. Those two sentences define what the repository is. There is no application to install and no server to run. The repository contains a style, written in CartoCSS, plus the glue that assembles it into a TileMill project: a `make.py` script, a `configure.py.sample` template, an `imposm-mapping.py` import configuration, a `lib/` directory, and the `osm-bright/` directory holding the style itself. The primary language of the repository is recorded as CartoCSS, which tells you where the work happens. Rendering is TileMill's job, and the tiles your users see are produced by TileMill interpreting the style against your own PostGIS database. The README is candid about the state of the style. It says the style is still a work in progress and that you are encouraged to use the issue tracker to note missing features or problems with the current implementation. So the expectation is that you will change it, and that you will report what you find. The licence is BSD 3-Clause with a `LICENSE.txt` at the root, the repository is not archived, and the last push was on 2026-06-29. ## Two large shapefiles come first The setup instructions start with data rather than with style, because the style references features that come from those shapefiles. OSM Bright depends on two large shapefiles, which you need to download and extract before continuing, into the `shp` directory in the osm-bright folder. The README gives the commands with `wget`: ``` wget http://data.openstreetmapdata.com/simplified-land-polygons-complete-3857.zip wget http://data.openstreetmapdata.com/land-polygons-split-3857.zip ``` There is a third, smaller file, needed only if you use what the README calls the osm2pqsql style: ``` wget http://mapbox-geodata.s3.amazonaws.com/natural-earth-1.4.0/cultural/10m-populated-places-simple.zip ``` That file is the Natural Earth populated places dataset at 1.4.0, and it is what gives you labels for settlements that are not in the OSM extract you import. The words large are doing work in that sentence, and so is the 3857 in the filenames, which is the Web Mercator projection the shapefiles are pre-projected into. If your database is in another projection, the style and the shapefiles are not going to line up, and the README does not discuss changing that. Once downloaded, you extract them from their zip files into the `shp` directory, and the next step assumes they are there. ## shapeindex, and a manual download on Windows The next step is to run the shapefiles through shapeindex, which the README describes as a tool that improves performance for shapefiles in Tilemill. The instructions are to go to the terminal, move to the shp directory of osm-bright, and run shapeindex in each shp subdirectory: ``` shapeindex land-polygons-split-3857.shp ``` The platform split in that step is worth reading. Mac and Linux users already have shapeindex installed through TileMill, but Windows users will need to download it before continuing, and the link given is an archived build, `shapeindex-2.2.0-win-x86_32.zip`, hosted on an S3 bucket under the mapnik distribution path. Two things follow. The first is that the tool is required, not optional: without it the shapefiles are unindexed and the map is slow. The second is that on Windows you are installing a binary from an archive location, and the README does not say how new it is or who maintains it now. So the first hour of using this template is mostly downloads: two large shapefiles, possibly a third, an indexing run per shapefile directory, and on Windows an extra binary. ## PostGIS and two different import routes Step three asks for PostgreSQL installed and running with a PostGIS database set up within it, and step four asks you to import OpenStreetMap data into that database. The README lists the acceptable formats as `.osm.pbf`, described as binary and the smallest and fastest, `.osm.bz2` as compressed xml, and `.osm` as xml. Regional extracts are available from download.geofabrik.de and from the mapzen metro extracts, and the OSM wiki covers full planet downloads, which the README flags as very large. There are two import routes, and they are not equivalent. With Imposm, the README says you should use the included mapping configuration, which includes a few important tags compared to the default. The command it gives is: ``` imposm -U -d \ -m /path/to/osm-bright/imposm-mapping.py --read --write \ --optimize --deploy-production-tables ``` With osm2pgsql, the README says the default style file should work well: ``` osm2pgsql -c -G -U -d ``` The difference matters for the style, not just for the import. The Imposm path uses the repository's own `imposm-mapping.py`, so the tags the style expects are the ones that land in your database. The osm2pgsql path relies on the default style, which means you are trusting that the default maps what OSM Bright draws. If you mix the two, or import with one tool and set the other in the configuration, the failure mode is missing features rather than an error. ## configure.py.sample is where your project becomes yours Step five is the configuration, and the README is precise about it. You make a copy of `configure.py.sample` and name it `configure.py`: ``` cp configure.py.sample configure.py ``` Then you edit it. You make sure the `importer` option matches the program you used to import your data, either `imposm` or `osm2pgsql`. You optionally change the name of your project from the default, `OSM Bright`. You adjust, if needed, the path to point to your MapBox project folder. You make any adjustments to the PostgreSQL connection settings, since your database may be set up so that you require a password or a different user name. And you optionally adjust the query extents or shapefile locations, with the README pointing at the comments in the configuration file for more information. The `importer` option is the one to get right, because it tells the build which database layout to write queries against. Everything else is either a path or a credential, and both of those fail loudly in the log rather than silently. Note that the file is a Python script and that you edit a copy rather than the sample, so the sample stays a reference for what the options are. The `imposter` spelling is not in the file, it is the `importer` option, and the values are the two tool names. ## make.py assembles the TileMill project The build step is one script: ``` ./make.py ``` The README says this creates a new folder called `build` with your new project, customized with the variables you set in `configure.py`, and installs a copy of this build to your MapBox project folder. If you open up TileMill you should see your new map in the project listing, and clicking on the map takes you to the editing interface. Then comes the warning, and it is the part that trips up first-time users. The README says to have patience, because the first time the project opens it needs to download very large shapefiles before the map can render, which can take 5 to 10 minutes on a fast connection and longer on a slow one. It suggests keeping TileMill open, navigating back to the projects view and then back to the project editor view to check on its loading status, or checking the TileMill logs to see the download status of the remote files. So there are two large downloads, not one. You fetch the land polygon shapefiles by hand at the start, and TileMill then fetches its own copies when the project first opens. Only when the map tiles show up are you ready to start editing the template. ## Where this template stops being the obvious choice The honest limitation of OSM Bright is the toolchain it assumes, and the README makes no attempt to hide it. The workflow needs TileMill, it needs shapeindex from TileMill's own distribution, it needs a MapBox project folder as the install target, it needs a local PostGIS database, and it needs either Imposm or osm2pgsql on the machine. That is a set of components from a specific era of map tooling, and the Windows instructions point at an archived binary in an S3 bucket. The alternative approach is a current vector tile pipeline, where the style is expressed as a JSON document, the tiles are built by a contemporary tool, and the data import is handled by the same tool that renders it. The difference in approach is where the styling language lives. CartoCSS is a stylesheet with its own syntax, its own cascade and its own variables, aimed at a renderer that reads the database directly. A JSON style is a data structure aimed at a renderer that consumes prebuilt tiles, which moves the heavy database work into a separate build step but decouples the style from the database. Two smaller observations. The style is unfinished by the project's own account, so you will be styling rather than configuring. And the repository has no GitHub releases, so there is no version to pin; the last push was on 2026-06-29, the repository is not archived, and a `CODEOWNERS` file is present, so somebody is still looking after it. The `lib/` and `osm-bright/` directories at the root are where the style and its supporting code live, and `preview.png` is the screenshot the README shows. ## Conclusion Adopt OSM Bright when you want a known good starting style for OpenStreetMap data inside TileMill, and when you are prepared to run the shapefile, PostGIS and import steps yourself. Do not adopt it as a current production tile pipeline, since the documented chain runs through TileMill and its shapeindex tooling rather than a modern vector tile stack, and do not expect the style to be finished, as the README calls it a work in progress. Verify first that the land polygon shapefile URLs still resolve, that the `importer` option in `configure.py` matches the tool you actually imported with, and that the PostGIS credentials in that file match your database, since a mismatch there produces an empty map rather than an error you will notice quickly. ## FAQ ### What is OSM Bright and what does it produce? OSM Bright is a styling template for making maps from an OpenStreetMap database, written in the Carto styling language and opened as a project in TileMill. Running make.py creates a build folder and installs the project into your MapBox project folder, where TileMill renders it. ### What does OSM Bright need before a map can render? Two large land polygon shapefiles in the shp directory, indexed with shapeindex, a PostgreSQL installation with a PostGIS database, and an OpenStreetMap extract imported with either Imposm or osm2pgsql. The README also notes that the first time the project opens in TileMill it downloads very large shapefiles, which can take 5 to 10 minutes on a fast connection. ### How do I tell OSM Bright which import tool I used? In the configuration file. You copy configure.py.sample to configure.py and set the `importer` option to either `imposm` or `osm2pgsql`, matching the program you actually imported your data with, along with the PostgreSQL connection settings, the project name and the path to your MapBox project folder. ### Is OSM Bright finished? The README says the style is still a work in progress and encourages using the issue tracker to note missing features or problems with the current implementation. The repository is not archived, the last push was on 2026-06-29, and it publishes no GitHub releases. ## Sources - [Issues](https://github.com/mapbox/osm-bright/issues) - [License: BSD-3-Clause](https://github.com/mapbox/osm-bright/blob/master/LICENSE) - [mapbox/osm-bright on GitHub](https://github.com/mapbox/osm-bright) - [README](https://github.com/mapbox/osm-bright/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mapbox-osm-bright