Offline sideloading

Offline sideloading is a two-part process for making offline regions available to mobile apps. The Maps SDK for iOS makes it possible to pre-generate an offline map within an application so that the resulting offline map can be bundled automatically when an end user downloads your application.

Offline sideloading differs from downloading pre-selected regions that a device can use when it does not have network connectivity, which is documented in the Offline maps troubleshooting page. Downloading pre-selected regions can work well for smaller regions where there are not a large number of resources to download. But because tiles are downloaded individually, this approach can be too slow for larger regions. In cases like this, offline sideloading can provide a better solution.

This guide outlines how to generate an offline package outside of an SDK, either by using the Mapbox GL command line tool or by using the macOS graphical interface. This guide also describes how to merge the generated offline packages into the Maps SDK database to make them available to your mobile app.

Tile counts for offline sideloading

The extent of offline capabilities in your mobile app is limited to 6,000 tiles by default. If your requirements are different, contact Mapbox sales about moving to an Enterprise plan. You can calculate the number of tiles required for your offline use case with the Offline tile count estimator. For reference, six thousand tiles cover a region roughly the size of Greater London within the M25 at zoom levels 0–15, or the contiguous United States at zoom levels 0–9. The size of these tiles on disk will vary according to the selected style.

Generate an offline package with the command line tool

Using the Mapbox GL command line tool is ideal if you want to build your offline packages server-side (for example, in a container) or as part of an automated system like CI in which a graphical interface is either not necessary or not desirable. This option is best for developers who want to automate the offline package generation process.

Keep in mind that you will not be able to set a name or other metadata using the command line tool, since the metadata field is platform-agnostic.


CLI tool build instructions

  1. Clone the Maps SDK: git clone
  2. Change to the root folder: cd mapbox-gl-native
  3. Compile the binary: make offline

Once the build is complete, you'll see the message Build Succeeded in the terminal. The binary is available under the build folder (for example, on a Mac the file will be in build/macos/Debug/mbgl-offline).

Download your offline package

  1. Delete your old database, if applicable. This will allow you to generate a new offline package without any interference from the previous setup.
  2. In the command line, change into to the folder where the mbgl-offline file is: cd build/macos/Debug
  3. Run the following command, using your own data as described in the Optional flags section:
./mbgl-offline --north [north coordinate] --west [west coordinate] --south [south coordinate] --east [east coordinate] --minZoom [minimum zoom] --maxZoom [maximum zoom] --output [output file path] --style [style URL] --token [mapbox token]

The tiles that you requested will begin downloading.

Example command:

./mbgl-offline --north 71.44117085172385 --west -26.015625 --south 28.07198030177986 --east 28.916015625 --minZoom 4 --maxZoom 4 --output ~/europe.db --style mapbox://styles/mapbox/streets-mapbox-streets-v7 --token <your access token here>

To see a few examples that you can reference when creating your region, take a look at /bin/

Optional flags

Use the following optional flags to customize your offline package:

--helpSee all available flag options.
--tokenThe Mapbox access token to use for downloading tiles.
--styleThe map style URL.
--outputThe name of the output database. You can choose any name for this file.
--northThe northern-most coordinate in the bounding box.
--eastThe eastern-most coordinate in the bounding box.
--southThe southern-most coordinate in the bounding box.
--westThe western most coordinate in the bounding box.
--geojsonA GeoJSON file that contains the region geometry.
--minZoomThe minimum zoom level you want your region to have.
--maxZoomThe maximum zoom level you want your region to have.
--pixelRatioPixel ratio (or pixel density) is a device-dependent value provided by the OS. To see sample values for popular devices, see the Material Design device metrics page.
--mergeThe database that will be merged into the database that you specify in --input.
--inputThe database you want to merge into. Must be used with the --merge option.

Warning: Take the available memory size into consideration when you choose your bounding coordinates and the minZoom and maxZoom levels.

Generate an offline package with the macOS graphical interface

Using the macOS graphical interface is a good approach if you create offline packages relatively infrequently, if you prefer a visual tool to generate your packages, or both.

This method of generating offline packages is only applicable to macOS users. For users with other operating systems, including Linux, we recommend using the CLI tool as described in the Generate an offline package with the command line tool section of this documentation.


  • Mapbox requires macOS 10.11 or above.

Generate an offline package

Mapbox is an application that demonstrates the Mapbox Maps SDK for macOS. The iOS and macOS Maps SDKs are largely compatible with one another and use an identical offline storage format.

  1. Delete your old database, if applicable. This will allow you to generate a new offline package without any interference from the previous setup.
  2. Download the latest release of the Mapbox Maps SDK for macOS from the Mapbox GL Native repository’s release page.
  3. Unzip and open Mapbox
  4. Go to the View menu and select the map style to use. You can also use the menu in the toolbar to select a style. To choose a custom style designed in Mapbox Studio, go to View ‣ Custom Style and enter the appropriate style URL.
  5. Resize the window and adjust the map so that the extent of the desired offline package are fully visible in the window.
  6. Go to Window ‣ Offline Packs.
  7. Click the + button to create a new offline package. Enter a name for this offline package, then click Add. Repeat this step for any offline packages you want to download.

Once an offline package finishes downloading, it will be completely contained in the offline database file at the path: ~/Library/Application\ Support/com.mapbox.MapboxGL/.mapbox/cache.db

The cache.db created using this approach may also contain ambient tiles for the loaded style (and possibly from previously loaded styles) that were cached incidentally while you used Mapbox As such, this method for generating an offline package is good for testing, but it does not produce the smallest possible database size.

What if I need to create a custom macOS application?

If you need to generate an offline package that specifies metadata beyond name and zoom level, then you will need to use the macOS SDK to create a custom macOS application to download offline packages.

For this method of generating offline packages, the implementation is up to your individual development choices. However, you can consult the MGLOfflineStorage documentation or the Download an offline map example for examples of how to build the offline downloading harness.

Merge the offline package

Once you’ve created a new offline package, you will need to merge its contents into the main Maps SDK database. You have two options for merging the offline package into the main database of an application:

  • Bundle the offline database file, then download it.
  • Download the offline database file after installation.

No matter which approach you take, you will use either the -[MGLOfflineStorage addContentsOfFile:withCompletionHandler:] or the -[MGLOfflineStorage addContentsOfURL:withCompletionHandler:] methods to load the offline package to the main Maps SDK database.

Bundle and download the file

You can bundle the offline database file with your application prior to installation, then download it to your application from the bundle location. This approach works well for most use-cases.

If you choose this approach, then you need to explicitly make a copy of the offline database file to a writable location before merging it. MGLOfflineStorage requires that this file be writable so that the offline database can be upgraded in place if necessary (if, for example, it uses an older database schema than the application's main database does). You will need to do this with code, but the implementation will be up to you. One possible approach, which uses the built-in iOS NSFileManager to make a copy of the offline database, is demonstrated in this example

Download the file after installation

Your application can also download the offline database file after installation, and then merge it. This method is useful in cases in which you need to build offline packages server-side in a container (for example, to regenerate a set of predefined regions whenever a style or tileset changes).

The implementation details of downloading the offline database file are up to you.

If the offline database file is downloaded after installation, then it necessarily resides in a writable location, and you do not need to make a copy of it as you would if you were bundling prior to installation.

Load the offline database

After you have either bundled and downloaded the offline database file or downloaded the file after installation, then you will load the offline database file.

To add the contents of the file to the offline storage, use the -[MGLOfflineStorage addContentsOfFile:withCompletionHandler:] method or the -[MGLOfflineStorage addContentsOfURL:withCompletionHandler:] method to merge the offline database into the application's main map cache database. Both methods are described in the MGLOfflineStorage documentation. The loaded database's styleURL must correspond with the application's styleURL.

let databaseURL = temporaryPathURL.appendingPathComponent("cache.db")
try! FileManager.default.copyItem(at: sourceURL, to: databaseURL)
MGLOfflineStorage.shared.addContents(of: databaseURL, withCompletionHandler: nil)

Once the sideloaded database's contents are merged into the main database, they will be available for future user requests.

You should regenerate the sideloading database whenever you upgrade the Maps SDK. This is especially important if the database is bundled with the application.

Learn more

For more detailed information about the methods outlined here, see the Mapbox Maps SDK for macOS Offline Maps documentation.