# OpenFreeMap: Serving 300 Million Vector Tiles Without a Tile Server

> OpenFreeMap hosts OpenStreetMap-derived vector tiles for free and publishes its full production setup. The design choice that defines it is unusual: no tile server process at all, just Btrfs images and nginx.

**hyperknot/openfreemap** — Free and open-source map hosting solution with custom styles for websites and apps, using OpenStreetMap data

- Repository: https://github.com/hyperknot/openfreemap
- Website: https://openfreemap.org/
- Stars: 6,125 · Forks: 195
- Language: Python
- License: NOASSERTION
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/hyperknot-openfreemap

## The problem OpenFreeMap picks, and the ones it refuses

Basemap hosting is the part of a mapping project nobody wants to own. You need vector tiles for the whole planet, a style that looks acceptable, and enough bandwidth to survive a traffic spike. Commercial providers solve this and charge for it. OpenFreeMap's answer is to give the tiles away and publish the machinery that produces them.

The scope is deliberately narrow. The README lists what the project is not providing: search or geocoding, route calculation and navigation, static image generation, raster tile hosting, satellite imagery, elevation lookup, and custom tile or dataset hosting. That list is the most useful thing on the page, because it tells you in one read whether OpenFreeMap fits. If your application needs a pin dropped at an address the user typed, you still need a geocoder from somewhere else.

The audience is developers who want a MapLibre-compatible basemap for a website or app, either by pointing at the public instance or by running their own copy on dedicated hardware. The public instance has no registration, no API keys, no user database and no cookies, and the README states there are no limits on map views or requests. Running costs are covered by donations.

## No tile server: Btrfs images and hard links instead of a running service

This is the part worth understanding before anything else. The README states plainly that there is no tile server running, only Btrfs partition images containing 300 million hard-linked files. The average file is about 450 bytes.

The pipeline that produces those images is documented in the repository. The tilegen component downloads a full planet OSM extract and runs it through Planetiler. The resulting .mbtiles file is extracted into a Btrfs partition image by a custom helper, tilegen/tilegen_lib/mbtiles.py, and the partition is shrunk by tilegen/tilegen_lib/btrfs.py. The image is then uploaded to a public Cloudflare R2 bucket using rclone.

On the serving side, linux_host downloads those Btrfs images, downloads assets, mounts the images, fetches version files, and runs a sync cron task that fires every minute when auto_update is enabled. nginx on Ubuntu 24.04 serves the mounted files. There is no application process in the request path, so there is nothing to warm up, no cache to prime and no worker pool to tune. The README credits Planetiler with cutting tile generation from 5 weeks to 5 hours.

That architecture has a cost the README does not hide: only use the auto_update linux_host if you keep a close eye on this repo. Automatic updates are not promised to be worry-free for self-hosters.

## Installing OpenFreeMap on a clean Ubuntu 24.04 server

The README is explicit that OpenFreeMap is not something you install locally. The repository is a deploy script built around Fabric that runs commands over SSH against clean Ubuntu 24.04 servers or virtual machines. It is Docker-free on purpose, and the README invites someone else to build a Docker version and have it linked.

Python 3.13 or newer is required according to pyproject.toml. The repository ships a prepare-virtualenv.sh script and a uv.lock file, which points at uv as the toolchain. The commands below follow the repository layout; run them from a clone of the repository on your control machine, not on the target server.

```bash
./prepare-virtualenv.sh
```

After that, the two deployment entrypoints are linux_host/deploy_linux_host.py and tilegen/deploy_tilegen.py. Each sets up a clean Ubuntu 24.04 machine over SSH. The README describes a single command being able to set up a production-ready server for both components.

```bash
python linux_host/deploy_linux_host.py --help
python tilegen/deploy_tilegen.py --help
```

Those help commands are the honest first step, because the README does not reproduce the full flag set. Once a linux_host machine is provisioned, its runtime entrypoint is linux_host/scripts/linux_host.py, and the README points to its own help output for available options.

```bash
./linux_host/scripts/linux_host.py --help
```

If you do not want to run any of this, the README says tilegen is 100 percent optional because processed full planet images are published for download weekly in both Btrfs and MBTiles formats. For a first real use, pointing MapLibre at the public instance is the shortest path: the README states that https://tiles.openfreemap.org/planet/latest always points to the latest deployed version. Styles live in a separate repository, hyperknot/openfreemap-styles, which the README says is continuously developed while this repository is intended to change rarely.

## Where OpenFreeMap is the wrong tool

The limitations section is a design statement, not an apology, and it should be read as a hard boundary. No geocoding means no address search. No routing means no directions. No raster tile hosting means you cannot ask for PNG tiles for a legacy client. No satellite imagery means no aerial basemap. No elevation lookup means no terrain profiles. No custom tile or dataset hosting means you cannot push your own data through this pipeline and get it served back.

The second limitation is operational. Because the repository is a Fabric-based deploy script rather than a packaged application, it does not run on macOS or Windows as a local service, and it does not fit a container-first workflow. The README acknowledges this directly and says a Docker-based version would be welcome, which is a fair signal that none exists here.

The third is the update story. Self-hosters who enable auto_update are told to watch the repository closely. If your team cannot monitor a cron-driven sync task that runs every minute, the public instance is the safer choice, and the README offers it without limits.

One more gap: the README does not document rollback for a bad tile image or a failed sync. That silence matters if you are planning a production deployment, because the sync task runs continuously and the README does not describe how to revert a version.

## OpenFreeMap versus a tile server such as Tegola or a hosted provider

The obvious alternative is a conventional vector tile server. Projects in that space read tiles from a database or an MBTiles archive and render them on demand, usually with a cache in front. The difference is where the work happens. A tile server does work per request and needs memory, CPU and a cache layer sized for your traffic. OpenFreeMap does the work once, at generation time, and then serves static files from a mounted Btrfs image. The README frames this as replacing a running service with a file-system-level implementation, and argues that Linux file caching is among the most thoroughly tested code paths available.

That trade is real in both directions. You give up the ability to change a style or a dataset and see it immediately, because the artifact is a planet-sized image produced by a weekly pipeline. You gain a serving path with no application logic in it. The README reports a benchmark on a Hetzner server that reached 30 Gbit on the loopback interface with a cold nginx cache, and notes that the benchmark documents and tools remain in docs/benchmark/README.md while deployment no longer exposes benchmark or hard-coded debug operations.

Against a commercial hosted provider, the difference is less architectural than contractual. OpenFreeMap publishes the full production setup with no open-core split, and the public instance requires no account. What you cannot get from it is the adjacent services a commercial platform bundles, which is precisely the list in the limitations section.

## Maintenance, releases and the licence question

The last push to this repository was on 2026-09-13, nine days before this writing, so the codebase is current. That said, the README describes the intended commit pattern as few commits here while tiles generate automatically, servers update automatically and load balancing absorbs downtime. A quiet repository is the design goal, not a warning sign, but it does mean you should not expect rapid responses to issues filed against the deployment scripts.

Upgrade cost concentrates in the sync path. The linux_host cron task runs every minute when auto_update is enabled, so a change to the upstream image format or the version files propagates without a manual step. That is convenient and also the reason the README warns self-hosters to watch the repository. There are no retrieved releases for this project, so there is no changelog to scan before an upgrade; the commit history is the changelog.

The licence field resolves to NOASSERTION, and the repository contains a LICENSE.md. The README does not state the licence terms in prose, and this article will not guess at them. If you plan to redistribute the tiles or the deployment scripts, read LICENSE.md yourself and check the upstream terms for OpenStreetMap data, OpenMapTiles, Planetiler, MapLibre, Natural Earth and Wikidata, all of which the README names as components. That is a factual checklist, not legal advice.

## Conclusion

Adopt OpenFreeMap if you need a basemap layer and are willing to accept that tiles are all you get: no geocoding, no routing, no raster or satellite imagery. Use the public instance if you want zero setup, and read docs/self_hosting.md before committing to your own servers. Skip it if you need a single binary you can run on a laptop, because the deployment scripts target clean Ubuntu 24.04 machines over SSH. Before adopting, verify two things: that the styles in the separate styles repo render the features you need, and that you are comfortable with the licence situation, since the repository carries a NOASSERTION licence identifier and the README does not spell out the terms.

## FAQ

### What are the key differences between OpenFreeMap and OpenStreetMap?

OpenStreetMap is the data source; OpenFreeMap is a hosting solution that turns that data into vector tiles and serves them, either from its public instance or from your own servers. OpenFreeMap does not provide search, routing, raster tiles, satellite imagery or elevation lookup.

### How do I use OpenFreeMap?

The README points to https://openfreemap.org/ as the quick introduction and how-to guide, and states that https://tiles.openfreemap.org/planet/latest always points to the latest deployed tile version. For self-hosting, the repository is a Fabric-based deploy script that sets up clean Ubuntu 24.04 servers over SSH, documented in docs/self_hosting.md.

### Is there an OpenFreeMap alternative if I need routing or geocoding?

OpenFreeMap states by design that it does not provide search or geocoding, route calculation, navigation or directions, so those capabilities have to come from another service. Within tile hosting, the alternative approach is a conventional tile server that renders from a database or MBTiles archive per request instead of serving prebuilt Btrfs images.

## Sources

- [hyperknot/openfreemap on GitHub](https://github.com/hyperknot/openfreemap)
- [Issues](https://github.com/hyperknot/openfreemap/issues)
- [Project website](https://openfreemap.org/)
- [README](https://github.com/hyperknot/openfreemap/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hyperknot-openfreemap