protomaps basemaps builds a whole-country basemap on your own machine in a couple of hours

A basemap as one file you can host anywhere

The Protomaps basemaps repository builds a cartographic basemap PMTiles file from OpenStreetMap and other datasources, and it also provides the MapLibre styles for displaying those tiles in a browser. The project description calls it basemap PMTiles generation and cartographic styles for OpenStreetMap data and more.

The format choice is the interesting part. PMTiles is a single file archive of map tiles, and the README states that no restrictions apply to the underlying .pmtiles format, which it describes as an open specification in the public domain. One file means one object to host, one thing to cache, and a way to serve tiles by range requests without a tile server stack or a database behind it.

The basemap is not a bare tile dump. It is a designed basemap, with a visual design that the project publishes as part of the repository, which is why the repository carries both the generation pipeline and the styles.

The examples linked at the top of the README are the fastest way to understand the intended use: displaying markers on a map, changing the map theme and language, and sandwiching your own data between map layers. That last one is the pattern most teams end up wanting, a basemap underneath and your own data on top, with the basemap's styling not fighting your own.

The homepage is maps.protomaps.com, the single page app for viewing and downloading builds, and the repository is written in Java for the tile pipeline with a TypeScript package for the styles.

Three parts: tiles, styles and the viewing app

The README organises the repository into parts, and the split is the clearest description of the project.

The app directory is a single page app at maps.protomaps.com for viewing and downloading basemap builds. The tiles directory is a Planetiler build profile that generates planet.pmtiles from OpenStreetMap and Natural Earth in two to three hours on a modest computer. The styles directory is a TypeScript package that generates MapLibre GL styles in multiple colour themes, usable through npm or exportable as JSON.

Each part can be used without the others, and that is the design's strength. You can take the styles and apply them to a tileset you built yourself, you can build a tileset and serve it with your own renderer, or you can run the app to look at what the project produces.

The Planetiler dependency is worth understanding, because it is what makes the tileset feasible. Planetiler is a Java tool that turns OpenStreetMap data into vector tiles, and this repository contributes a build profile to it rather than a tile generation engine of its own. The README links the Planetiler repository directly, and the development instructions require Java 21 or newer and Maven.

A profile is a layer of configuration and Java on top of Planetiler: the data sources, the feature filtering, the layers and their attributes. The alternative, running Planetiler with a stock configuration, gives you a generic schema of OSM tags, which is useful for analysis but not for a designed basemap, since the styling of a basemap depends on a curated set of layers and zoom-dependent rules.

The top level of the repository also holds render-tests/, a sprites/ directory and examples/ with basic.html, data_sandwich.html, local.html and theme_language.html, plus SEMANTIC-VERSIONING.md and a CHANGELOG.md.

Building a named area on a laptop, then viewing it locally

The development section is a five step procedure, and it is worth following literally because the steps assume a specific directory layout.

You need Java 21 or newer and Maven, which the README says is available in most package managers. Then clone the repository:

git clone [email protected]:protomaps/basemaps.git

Move into the tiles directory and build the JAR, which downloads dependencies and compiles:

cd basemaps/tiles
mvn clean package

Then download and generate the tiles for a named area, in this case Monaco, into the current directory:

java -jar target/*-with-deps.jar --download --force --area=monaco

The area flag is what makes this practical to try. Building the whole planet takes two to three hours on a modest computer, while a single city is minutes, so the same profile is used for both the local experiment and the full build.

To look at the result, switch to the app directory, which uses nvm to pick the Node version, installs with npm ci and starts the development server:

cd app
nvm use
npm ci
npm run dev

The README says the locally generated pmtiles can then be fetched from http://localhost:5173/monaco.pmtiles, which is the moment the build becomes something you can click on. Formatting is applied with mvn spotless:apply.

One rough edge worth knowing: the clone command uses the SSH form of the URL, so it needs a GitHub key configured, while a plain HTTPS clone works just as well if you prefer.

BSD-3 code, CC0 design, ODbL tiles, and a naming condition

The licensing section of the README is the most detailed part of the document, and it layers four different terms across the different outputs.

All code is BSD-3, and the software in this repository is made available under the BSD 3-Clause License, with the requirement to retain the license notices related to Protomaps LLC, Mapzen and the Linux Foundation in derived source code. The map design is released under Creative Commons Zero, which the README explains is there to eliminate ambiguity around derivative or combined works of map styling code, while the published software packages use the standard BSD-3 license.

The tilesets are a different matter. They are Produced Works of the OpenStreetMap dataset under the Open Database License, so web maps and native apps using that produced work must visibly attribute OpenStreetMap, for example in the corner of the map display. The README gives the exact form: a link to the Protomaps project followed by a copyright symbol and a link to OpenStreetMap. If your map uses only the styles with non-OpenStreetMap tilesets, that attribution is not required.

The naming condition is the clause people miss. If you distribute a modified fork of the styles or tilesets, or provide a tiles API based on them, you must name your product or service something different from Protomaps. Free and unmodified redistributions may keep the name. The README also asks, kindly rather than legally, that you attribute the project if you use the styles unmodified or with additions.

Data from Natural Earth and other sources does not require corner attribution, though other data sources you add may require their own, and LICENSE_DATA.md in the repository root covers that. Some map styles include MIT-licensed icons from the Tangram Icons repository.

Styles generated in TypeScript rather than drawn in an editor

The styles package is the part of this project that changes how a team works, and it is the reason the repository is not only a tile pipeline.

The styles directory is a TypeScript package that generates MapLibre GL styles in multiple colour themes, and those styles can be used via npm or exported as JSON. That means the visual design of the map is code. It is reviewable in a pull request, diffable when a layer changes, and reproducible, which is not true of a style edited by hand in a GUI and exported as a blob.

The second benefit is theming. The repository ships several colour themes, and the theme_language.html example shows changing both the theme and the language of the map. Since the styles are generated, adding a theme means adding a configuration, and switching themes at runtime means swapping a style reference rather than rebuilding assets.

The MapLibre GL target is worth noting because it defines who can use the output. The topics attached to the repository also include OpenLayers, so the project is aware of the wider vector map ecosystem, but the style format documented here is MapLibre GL's, and a renderer that does not read that format needs a conversion step that the README does not describe.

Fonts and sprites are not in this repository. Assets such as fonts and sprites are hosted and downloadable from the separate basemaps-assets repository, which keeps the binary weight of this repository down and makes the style package depend on a fixed set of hosted assets.

An evolving pipeline with its own versioning rules

The repository carries the paperwork of a project that changes shape over time, and that paperwork is part of what you inherit when you build on it.

There is a SEMANTIC-VERSIONING.md at the root, a CHANGELOG.md and a CONTRIBUTING.md, plus LICENSE.md and the separate LICENSE_DATA.md for data attribution. A render-tests/ directory suggests that the appearance of the generated map is checked automatically, which is the only sensible way to guard a cartographic design that is defined in code.

The examples directory holds plain HTML files, basic.html, data_sandwich.html, local.html and theme_language.html, which are the same examples the README links. The root package.json is a minimal wrapper for the repository as a whole, with an http-server dev dependency and a test script that reports that no test is specified, so the real test surface is elsewhere: the Maven build for the tiles and the render tests for the styles.

On maintenance, the last push to the main branch was on 2026-09-11, and the repository has no GitHub releases, so the version of the styles package you get is the version in the repository or on npm rather than a tagged release.

For anyone planning to ship a basemap, the summary in the README is the checklist to work through: name your fork, commercial product or service something different, keep the OSM attribution visible, and treat the map design as CC0 so that your own derivative work stays unambiguous.

Editorial conclusion

protomaps basemaps fits teams that want a self-hosted basemap without paying a tile provider, that need a single file rather than a tile service, and that want to theme the map in code rather than in a style editor, and it fits anyone who wants to reproduce the Protomaps look on their own data. It is the wrong choice if you need a hosted tiles API with a service level agreement, and it is the wrong choice if you cannot accept the ODbL obligations that come with OpenStreetMap data. Verify first that the planet.pmtiles build fits your disk and time budget, that your renderer reads PMTiles and MapLibre GL styles, and that your product name does not collide with the Protomaps name if you fork the styles or run a tiles API based on them.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. protomaps/basemaps on GitHub
4. README