An offline map usually means a folder with thousands of small tile images, or a tile server you have to run. PMTiles is a simpler idea: the whole map is one file, with an index at the start that says where each tile sits. A reader needs only the header, a few directories and the tiles on screen. The same file can sit on a phone's storage or on a plain static host, where the reader fetches byte ranges over HTTP.
pmtiles_provider brings that to flutter_map. It is a TileProvider for raster PMTiles v3 archives. You can show a single-file map offline from a file, an asset or memory, or stream it from any static host with HTTP range requests.
One thing to say up front: it draws raster tiles (PNG, JPEG, WebP). It is not a vector tile renderer. Opening an MVT archive fails with a clear error that points you to a vector renderer.
What it does
Four sources. PmTilesProvider.fromFile, .fromBytes, .fromAsset and .fromUrl. On files, access is random: only the header, the directories and the visible tiles are read. File access sits behind a conditional import, so the package still compiles for the web.
HTTP range requests with change detection. fromUrl sends Range requests and tracks the ETag, Last-Modified and size of the archive. If the archive is replaced on the server in the middle of a session, the change is detected, the caches are dropped, the request is retried, and provider.changes fires so TileLayer.reset can reload the stale tiles.
Caches. There is an LRU cache for leaf directories (by count) and one for tile bytes (by size). Both sizes are configurable. The header and the root directory come from a single 16 KiB read.
Metadata. provider.info() gives the bounds, center, min and max zoom, tile type, name and attribution of the archive. info.mapOptions() builds MapOptions from it, so the map opens on the right place.
Missing tiles. A missing tile can be transparent, an error (so TileLayer.errorImage shows), or overzoomed: the nearest ancestor tile is cropped and scaled up. Overzoom also fills zooms deeper than the archive's max zoom.
Cancellation. A tile that leaves the screen aborts its pending range read. Reads shared by several tiles are aborted only when every waiting tile has cancelled.
A reader written from the spec. The PMTiles v3 reader covers the header, varint and delta directories, run lengths, leaf directories, Hilbert TileIDs and gzip.
How to use it
Add it from GitHub, next to flutter_map and latlong2:
dependencies:
flutter_map: ^8.0.0
latlong2: ^0.9.1
pmtiles_provider:
git: https://github.com/AbdeldjalilChougui/pmtiles_provider
Then give the provider to a TileLayer:
import 'package:flutter/material.dart';
import 'package:flutter_map/flutter_map.dart';
import 'package:pmtiles_provider/pmtiles_provider.dart';
class OfflineMap extends StatefulWidget {
const OfflineMap({super.key, required this.path});
final String path;
@override
State<OfflineMap> createState() => _OfflineMapState();
}
class _OfflineMapState extends State<OfflineMap> {
late final provider = PmTilesProvider.fromFile(
widget.path,
missingTile: const MissingTileBehavior.overzoom(),
);
late final info = provider.info();
@override
Widget build(BuildContext context) {
return FutureBuilder<PmTilesInfo>(
future: info,
builder: (context, snapshot) {
final info = snapshot.data;
if (info == null) return const SizedBox();
return FlutterMap(
options: info.mapOptions(), // center, zoom, bounds from the archive
children: [
TileLayer(
tileProvider: provider,
reset: provider.changes,
userAgentPackageName: 'com.example.app',
),
],
);
},
);
}
}
The other sources look like this:
PmTilesProvider.fromUrl('https://cdn.example.com/region.pmtiles');
PmTilesProvider.fromAsset('assets/region.pmtiles'); // loaded into memory
PmTilesProvider.fromBytes(bytes);
Every constructor accepts cache sizes: directoryCacheSize: 64 and tileCacheBytes: 8 * 1024 * 1024.
You can check an archive before showing the map. provider.validate() throws a PmTilesTileTypeException when the archive holds vector tiles.
Getting an archive
The README describes the offline workflow with the pmtiles CLI from the go-pmtiles project. You either convert raster MBTiles that you made with QGIS, GDAL or similar tools, or cut a region and a zoom range out of a larger raster archive:
pmtiles convert my_raster.mbtiles my_raster.pmtiles
pmtiles extract https://example.com/world_raster.pmtiles algiers.pmtiles \
--bbox=2.8,36.6,3.3,36.85 --maxzoom=14
pmtiles show algiers.pmtiles # check "tile type: png|jpg|webp"
The archive you extract from must be raster. Protomaps basemap builds are vector (MVT), and those need a vector renderer.
A small archive can be bundled as a Flutter asset and opened with fromAsset. Asset bundles have no random access, so the whole asset is read into memory. For archives larger than a few MB, the README shows how to copy the asset to a file once, or download it to the documents directory, and then use fromFile.
Hosting for fromUrl
Any static host that supports range requests works: S3, R2, GCS, nginx, GitHub Pages. On the web, the server's CORS policy must allow the Range request header and expose ETag and Content-Range. The first request asks for bytes 0-16383; later requests fetch one leaf directory or one tile each. A server that ignores Range and returns 200 still works, but each request then downloads the whole file.
Things to know
- Raster only. PNG, JPEG and WebP, plus the "unknown" tile type, which is passed to Flutter's decoder. MVT, MLT and AVIF archives are rejected.
-
Compression. gzip and none are supported. brotli or zstd archives throw
PmTilesUnsupportedException; re-encode them with gzip. - Zoom. TileIDs are exact up to zoom 26, the most that fits in a web-safe integer.
-
Web.
fromFileis not available on the web and throwsUnsupportedError.fromAssetandfromByteskeep the whole archive in memory. -
Change detection relies on the server sending a strong
ETag, aLast-Modifiedheader, or aContent-Rangetotal. Weak ETags are ignored. Tiles already on screen stay until the layer reloads them, which it does if you passprovider.changestoTileLayer.reset. -
Overzoom or maxNativeZoom. If you only need to go past the archive's max zoom and the archive has no holes,
TileLayer(maxNativeZoom: info.maxZoom)does the upscaling inside flutter_map and is cheaper. Overzoom in the provider also fills holes, such as extracts where the deepest zooms cover only part of the area. -
What was tested. The reader is checked against the spec's own TileID table, an independent test-only writer, and an archive produced by the official
pmtilesCLI. Behaviour is covered by VM unit tests and flutter_map widget tests. It is not yet verified on a real device or in a browser.
Why I built it
The README is direct about why this is a new reader and not a wrapper around the existing Dart pmtiles package. That package is a sound reader, but it requires a newer Dart SDK than this package supports, its archive and HTTP reader import dart:io unconditionally (so apps that use it cannot build for the web), it has no ETag or change detection, no request cancellation and no tile cache, and it pulls in dependencies that a raster provider does not need.
The flutter_map side had a gap too: flutter_map_pmtiles was last released in February 2025. So I implemented the small part of the v3 spec that a raster provider needs, and built the provider around the things a map on a phone runs into: tiles scrolling off screen before they load, archives with holes, and a file that changes on the server while the app is open. Besides Flutter, the package depends only on flutter_map, http, latlong2 and archive (for pure-Dart gzip).
If you are coming from flutter_map_pmtiles, the README has a migration table. The short version: PmTilesTileProvider.fromSource(url) becomes PmTilesProvider.fromUrl(url), which is synchronous, so no FutureBuilder is needed just to create the provider.
Get the code
The source, the offline workflow, the migration table and the tests are on GitHub: https://github.com/AbdeldjalilChougui/pmtiles_provider. It's MIT licensed. Issues and pull requests are welcome.
Originally published at abdeldjalilchougui.biz.
Top comments (0)