Why convert MBTiles to PMTiles
MBTiles has been the standard way to pack a whole set of map tiles into one file for over a decade, and tools like TileMill, Mapbox Studio, and QGIS still export it by default. But an MBTiles file is a SQLite database, which means reading even one tile out of it requires a SQLite engine, whether that is a mobile app's embedded library or a full tile-serving process running on a server somewhere.
PMTiles removes that requirement entirely. It is a single flat binary file where every tile lives at a known byte offset, addressed through a small directory that a client can download once and cache. A browser or map library then fetches individual tiles using ordinary HTTP range requests, which means a PMTiles file can be served directly from a static file host like S3, Cloudflare R2, or GitHub Pages, with no tile server, no database, and no backend process at all.
This tool bridges the two formats without any installation. Drop in an MBTiles file and it reads the tile table directly out of the embedded SQLite database, corrects for the coordinate difference between the two formats, and assembles a valid PMTiles file byte by byte, all inside your browser tab.
How the conversion works
No existing JavaScript or WebAssembly library can write a PMTiles file — the official "pmtiles" package is a reader only, built for consuming archives over HTTP, not producing them. So this converter implements the PMTiles v3 binary format directly from its published specification: a 127-byte header holding the file's offsets, zoom range, and bounds; a gzip-compressed directory of tile locations; and the raw tile bytes themselves.
Two details matter most for a correct conversion. First, MBTiles stores tile rows in "TMS" order, counting from the south, while PMTiles counts from the north like most modern web maps; the converter flips every tile's Y coordinate with the standard formula before using it. Second, PMTiles does not address tiles by z/x/y directly — each tile gets a single ID from a Hilbert space-filling curve, chosen specifically because it keeps geographically nearby tiles close together in the resulting file, so a map viewer can load a small area using very few HTTP requests. Every tile is sorted by this ID, written into the file in that order, and indexed in a compressed directory that a reader binary-searches to find any given tile.
The output of this converter was verified using the official "pmtiles" reader library itself, the same code MapLibre GL uses to open real archives, confirming that every tile it writes comes back byte-identical when read back, for both small tilesets and archives large enough to require the format's directory-splitting for very large tile counts.
Step-by-step guide
Choose an .mbtiles file from your computer, or click "Try sample" to load a small synthetic tileset generated on the spot.
The source tiles are read from the MBTiles file and drawn on the map, so you can confirm the right tileset was loaded before converting.
Click "Convert to PMTiles". The conversion runs entirely in your browser: reading every tile, computing its Hilbert-curve position, and assembling the PMTiles file.
A summary appears: how many tiles were converted, the zoom range, the tile format, the geographic bounds, and the resulting PMTiles file size.
Click "Download .pmtiles" to save the finished file to your computer.
Real-world use cases
Where moving from MBTiles to PMTiles actually pays off.
- Publishing tiles on a static file host. PMTiles can be served straight from S3, Cloudflare R2, GitHub Pages, or any plain file host using HTTP range requests, with no tile server process running at all — something a MBTiles SQLite file cannot do on its own.
- Modernizing an old MBTiles export. Tile packages exported years ago from TileMill, Mapbox Studio, or QGIS are commonly still MBTiles. Converting them to PMTiles makes them usable in current map stacks (MapLibre, Protomaps) without re-generating the tiles from source data.
- Reducing infrastructure for a small map project. A single static PMTiles file removes the need to run and maintain a dedicated tile server just to serve a modest, mostly-static tileset, cutting hosting cost and moving parts for smaller sites and internal tools.
- Preparing offline map packages for field apps. Field data collection and offline-first mapping apps increasingly read PMTiles directly from local storage. Converting existing MBTiles basemaps means one file format across both the offline app and any web map that shares the same imagery.
- Archiving tilesets in a cloud-native format. Since PMTiles tiles are addressed by byte range rather than requiring database queries, an archived PMTiles file can be inspected, partially fetched, or served years later without needing any particular database engine installed.
Frequently asked questions
What is PMTiles, and how is it different from MBTiles?
Both pack a whole set of map tiles into one file, but MBTiles is a SQLite database, which needs a SQLite engine to read even one tile. PMTiles is a plain binary file designed so a web server (or even a static file host like S3 or GitHub Pages) can serve individual tiles using ordinary HTTP range requests, with no tile server or database running at all.
Does this tool actually implement the PMTiles format, or does it call some existing library?
It implements the PMTiles v3 binary format directly: the 127-byte header, the gzip-compressed tile directory addressed by a Hilbert-curve tile ID, and the tile data section. As far as we could determine while building this, no other browser-based JavaScript library can write a PMTiles file — the official "pmtiles" package is a reader only — so this had to be built from the published specification.
How was the output actually verified to be correct?
Every file this tool produces was tested by reading it back with the official "pmtiles" npm package's own reader, the same code MapLibre and other tools use to open real PMTiles archives, and confirming every tile comes back byte-identical. This was checked both for small files and for archives large enough to require the format's "leaf directory" splitting.
Why do the Y coordinates matter for this conversion?
MBTiles stores tile rows top-to-bottom in "TMS" order, counting from the south. PMTiles (like most modern web maps) counts from the north. The converter flips the Y coordinate for every tile using the standard formula, y_new = 2^z − 1 − y_old, before computing its position in the output file, so tiles end up in the right place.
Does this work for vector tiles as well as raster imagery?
Yes. The converter reads the "format" field from the MBTiles metadata table to tell PNG, JPEG, and WebP raster tiles apart from PBF/MVT vector tiles, and sets the correct tile type in the PMTiles header so that downstream tools like MapLibre GL know how to render them.
Will my metadata (name, description, attribution, vector layers) carry over?
Yes. The name, description, attribution, and — for vector tilesets — the "vector_layers" schema from the MBTiles metadata table are copied into the PMTiles metadata block, which is stored as plain JSON inside the file.
Is there a size or tile-count limit?
Uploads are capped at 100 MB. Very large tile packages (tens of thousands of tiles) take longer to process since every tile is read, hashed by its position on a Hilbert curve, and written out again, all inside your browser tab.
What happens to tile ordering inside the file?
Tiles are sorted by a Hilbert curve tile ID before being written, so tiles that are near each other on the map end up near each other in the file too. This is what lets a PMTiles reader fetch a small map area with very few HTTP range requests, instead of one request per tile.
Is my MBTiles file uploaded anywhere?
No. Reading the SQLite database, computing tile positions, compressing directories, and assembling the final PMTiles bytes all happen locally in your browser, using a WebAssembly build of SQLite. The file never leaves your device.
Conversion runs entirely in your browser using a WebAssembly build of SQLite. No file is ever uploaded to a server. Map tiles © OpenStreetMap contributors.
Basemap © OpenStreetMap contributors, drawn with Protomaps (hosted by KONAKTIVE), with CARTO as the fallback.
