OSM Liberty: a basemap style you can host yourself, and the account you still need

A fork of OSM Bright with a stated purpose

OSM Liberty is a free Maplibre and Mapbox GL basemap style for everyone with complete liberty to use and self host. It is a fork of OSM Bright based on free data sources with a mission for a clear good looking design for the everyday user, and it is based on the vector tile schema of OpenMapTiles.

The lineage explains the design. OSM Bright was the Mapbox style that put OpenStreetMap data on a Mapbox map, and it had a particular look: unobtrusive, muted, and built around the idea that a basemap should recede. The map design in this project originates from OSM Bright but strives to reach an unobtrusive and clean design for everyday use.

The one visual departure the README calls out is the relief shading. Colored relief shading from Natural Earth make the low zoom levels look good, and that is the feature that most distinguishes it from a plain road map at low zoom, where a vector-only style has little to draw.

The project lives in the Maputnik organisation, the default branch is gh-pages, the primary language recorded for the repository is Python, because of the small helper script it ships, and the last push was on 2026-10-14. There is no homepage set and the repository publishes no GitHub releases, since the artefact here is a style file rather than a package. The licence is a custom one GitHub cannot classify, with the file at LICENSE.md, and the badge describes it as BSD licensed.

Using the style means getting a tile key or hosting your own tiles

You can use the style in your Maplibre and Mapbox GL maps, and there is a preview linked that opens the style in Maputnik.

By default, the vector tiles are served from Maptiler Cloud and the relief shading, glyphs and sprites directly from GitHub. That split is worth understanding. The heavy part, the vector tiles, comes from a commercial cloud, and you would need to create a MapTiler account to get an access key and replace the placeholder {key} for the vector source with your own key.

So the default configuration is free in the sense that the style is free and the Maki icons, the Orange Mug glyphs and the Natural Earth relief are served from GitHub, but the tile hosting is a commercial service with a key. The two other options offered are to create your own vector tiles with OpenMapTiles and host the tiles yourself for complete liberty, or to use another vector tile source that is based on the vector tile schema of OpenMapTiles.

The second option is the one most people miss. Any source that speaks the OpenMapTiles schema will work, which means the style is not coupled to one provider, only the default happens to point at one.

The data sources are listed together at the end of the usage section: OpenMapTiles as the vector data source, Natural Earth Tiles for relief shading, Maki as the icon set, and Orange Mug as the font glyphs.

The pre-commit hook is what keeps a style JSON honest

The Edit the Style section contains the line that explains why this project is in the Maputnik organisation. This style actually triggered the need for the development of Maputnik, the style editor.

A Mapbox GL style is a JSON document with a schema, and it is easy to hand-edit it into a state that is technically valid JSON but does not render. A pre-commit hook is included to validate and format the JSON styles using the maplibre-gl-style-spec package. To use it, you install the npm dev dependencies:

npm install

and then validate or format the style with:

npm run validate
npm run format

Validation and reformatting happen automatically on commit if you have the dependencies installed.

The package.json confirms the mechanism. The validate script runs the gl-style-validate binary from node_modules against style.json, the format script runs gl-style-format writing to a temporary file and moving it over the original, and there is a diff script that shows what the formatter would change without changing anything. The husky configuration sets the pre-commit hook to run validate and format and then stage style.json.

That last part is the important detail. A style file is the entire artefact, so a commit that reformats it and stages the result means the repository never contains a style that the validator rejects. For a project where the deliverable is one large JSON file, that is a lot of value from a small amount of configuration.

The icon set and the two folders that are not Maki

The Icon Design section explains the icon system, and the practical part is the workflow rather than the design.

A Maki icon set is used, with colors to distinguish between icon categories. Maki is a living project and adds new icons over time, which means there could be new icons that OSM Liberty could use for points of interest. The repository ships sources_list.py, a simple script to list both the names in OSM Liberty's iconset that do not map to any valid Maki name, and the Maki names that are not currently used in OSM Liberty's iconset. You run it with python3 sources_list.py.

That script is a maintenance tool rather than a build tool, and it solves a real problem. An iconset that has drifted from its upstream cannot be regenerated by hand, and without knowing which entries are stale you would have to compare the two lists by eye.

The colour palette is small and fixed, with Blue at #5d60be, Light Blue at #4898ff, Orange at #d97200, Red at #ba3827, Brown at #725a50 and Green at #76a723.

The contributing instructions for icons are specific. When submitting a pull request, no need to include the sprites, because they are automatically created when merging a pull request. The size 11 icons are included in the sprites for backward compatibility, and new size 11 icons should not be included.

The workflow is to take iconset.json and import it into the Maki Editor, apply changes and download the icons in SVG format with the iconset in JSON format, and save the downloaded SVGs into the svgs_iconset folder. If the updated iconset.json should become part of the repository, the JSON has to be formatted with cat iconset.json | jq -MS '.' for better legibility.

There is a second folder, svgs_not_in_iconset, holding the SVGs for road shields, the dot used for city and town layers, and the road area pattern, none of which could be modified using the Maki Editor, and the README suggests a tool like Inkscape for those. The sprites are then generated with npm run build_sprites.

What the repository actually contains

The top level listing is short and each entry has a clear job.

style.json is the artefact. iconset.json is the icon manifest. The sprites/ directory holds the generated sprite sheets that a Mapbox GL style references, and svgs/ holds the source SVGs split between the two folders. build_sprites.sh is the script the npm script calls, and package.json wires the npm scripts to the style spec tools.

There is also a _config.yml at the root, which is a Jekyll configuration file. That is what a gh-pages branch needs to serve the style and the preview from GitHub Pages, and it explains why the default branch is gh-pages rather than main: the published site is the point of this branch, and the preview links in the README point at maputnik.github.io, which is GitHub Pages serving that branch.

The demo/ directory holds a zoom.gif, which is the animated preview used in the README to show the low zoom levels with the relief shading.

There is a link at the end of the README to OSM Liberty Topo, a topographic fork of OSM Liberty, which is a useful indicator of the ecosystem around it: the style has already been forked once for a specific cartographic purpose, and a style being forked that way is a reasonable signal that it is a workable base rather than a finished product.

The development tooling is minimal by design. The dev dependencies are the maplibre-gl-style-spec package and husky, and the package version is 0.1.0, which for a data artefact is really a version of the repository rather than a released library.

Editorial conclusion

Adopt OSM Liberty if you want a clean basemap style that is not tied to a commercial style vendor, and you are willing to run the tiles yourself or accept one account for vector data. Do not expect the default configuration to be fully self-hosted, because the vector tiles are served from Maptiler Cloud by default and the style carries a key placeholder. Before you deploy, either create a MapTiler account and substitute the key, or build your own vector tiles with OpenMapTiles and point the style at them, and note that this repository is published from its gh-pages branch rather than main.

Frequently asked questions

Official sources

1. Issues
2. maputnik/osm-liberty on GitHub
3. README