Coming from Mapbox

Web: what changes in your code

From Mapbox GL JS to MapLibre GL JS 6, the version this site runs. Most changes are renames; a few features work differently.

1. 01Package and import

   MapLibre GL JS v6 ships as ES modules only, so a default import no longer works: use a namespace import or named imports, and rename mapboxgl to maplibregl throughout your code.

   Mapbox GL JS

   npm install mapbox-gl
   
   import mapboxgl from 'mapbox-gl';

   MapLibre GL JS

   npm install maplibre-gl
   
   import * as maplibregl from 'maplibre-gl';
   // or: import {Map, Marker} from 'maplibre-gl';

2. 02Stylesheet

   Markers, popups and controls depend on this CSS, so swap the import rather than dropping it.

   Mapbox GL JS

   import 'mapbox-gl/dist/mapbox-gl.css';

   MapLibre GL JS

   import 'maplibre-gl/dist/maplibre-gl.css';

3. 03Loading from a CDN

   v6 loads as a module script and detects its worker from the module URL, and MapLibre's v5 to v6 guide advises pinning a major version such as ^6 rather than @latest.

   Mapbox GL JS

   <link href="https://api.mapbox.com/mapbox-gl-js/v3.30.0/mapbox-gl.css" rel="stylesheet">
   <script src="https://api.mapbox.com/mapbox-gl-js/v3.30.0/mapbox-gl.js"></script>

   MapLibre GL JS

   <link href="https://unpkg.com/maplibre-gl@^6.11.2/dist/maplibre-gl.css" rel="stylesheet">
   <script type="module">
     import * as maplibregl from 'https://unpkg.com/maplibre-gl@^6.11.2/dist/maplibre-gl.mjs';
   </script>

4. 04Access token

   MapLibre GL JS 2.0.0 removed all code related to accessToken, together with mapbox:// URLs and telemetry; to keep loading Mapbox tiles, Mapbox's own MapLibre guide passes the token as an access_token query parameter on HTTPS URLs.

   Mapbox GL JS

   mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
   // or: new mapboxgl.Map({accessToken: 'YOUR_MAPBOX_ACCESS_TOKEN', ...})

   MapLibre GL JS

   // Nothing to set: MapLibre GL JS has no access token

5. 05Style and source URLs

   MapLibre does not resolve mapbox:// URLs, so point styles and sources at a provider's HTTPS URLs (see Basemaps).

   Mapbox GL JS

   style: 'mapbox://styles/mapbox/streets-v12'

   MapLibre GL JS

   style: 'https://tiles.openfreemap.org/styles/liberty'

6. 06A style is required

   Mapbox GL JS v3 loads the Mapbox Standard style when no style is given, while MapLibre GL JS renders nothing until a style is set in the options or with setStyle.

   Mapbox GL JS

   const map = new mapboxgl.Map({
     container: 'map' // no style: Mapbox Standard loads
   });

   MapLibre GL JS

   const map = new maplibregl.Map({
     container: 'map',
     style: 'https://tiles.openfreemap.org/styles/liberty'
   });

7. 07CSS class names

   Custom CSS that targets mapboxgl- classes needs the maplibregl- prefix, since MapLibre GL JS 3.0.0 removed the deprecated mapboxgl- class names.

   Mapbox GL JS

   .mapboxgl-popup-content { padding: 8px; }

   MapLibre GL JS

   .maplibregl-popup-content { padding: 8px; }

8. 08Worker setup with a bundler

   With a bundler, MapLibre GL JS v6 needs one setWorkerUrl call before the first map (webpack 5 passes new URL('maplibre-gl/dist/maplibre-gl-worker.mjs', import.meta.url).toString()), and MapLibre's Installation docs cover esbuild, Rollup and Next.js.

   Mapbox GL JS

   import * as mapboxgl from 'mapbox-gl/esm';
   import 'mapbox-gl/dist/mapbox-gl.css';

   MapLibre GL JS

   import {Map, setWorkerUrl} from 'maplibre-gl';
   import 'maplibre-gl/dist/maplibre-gl.css';
   import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
   
   setWorkerUrl(workerUrl); // Vite; call once before the first map

9. 09Globe projection

   MapLibre GL JS sets the projection in the style or with setProjection rather than a Map option, and a style without one uses Mercator, whereas most current Mapbox styles use globe by default.

   Mapbox GL JS

   const map = new mapboxgl.Map({
     container: 'map',
     projection: 'globe'
   });

   MapLibre GL JS

   map.on('style.load', () => {
     map.setProjection({type: 'globe'});
   });
   // or in the style: "projection": {"type": "globe"}

10. 10Fog and atmosphere

    MapLibre's sky property (GL JS 4.5.0 and later, still marked experimental) uses its own property names for sky, horizon, fog and the globe atmosphere, so fog settings are rewritten rather than renamed.

    Mapbox GL JS

    map.setFog({
      color: 'rgb(186, 210, 235)',
      'high-color': 'rgb(36, 92, 223)',
      'horizon-blend': 0.02
    });

    MapLibre GL JS

    map.setSky({
      'sky-color': '#199EF3',
      'horizon-color': '#ffffff',
      'sky-horizon-blend': 0.5,
      'atmosphere-blend': 0.8
    });

11. 113D terrain source

    setTerrain takes the same options in both libraries; only the elevation source changes, here to Mapterhorn, whose TileJSON declares its Terrarium encoding and attribution.

    Mapbox GL JS

    map.addSource('mapbox-dem', {
      type: 'raster-dem',
      url: 'mapbox://mapbox.mapbox-terrain-dem-v1',
      tileSize: 512
    });
    map.setTerrain({source: 'mapbox-dem', exaggeration: 1.5});

    MapLibre GL JS

    map.addSource('terrain', {
      type: 'raster-dem',
      url: 'https://tiles.mapterhorn.com/tilejson.json'
    });
    map.setTerrain({source: 'terrain', exaggeration: 1.5});

12. 12Missing images

    In MapLibre GL JS v6 the styleimagemissing event only notifies, so supply generated icons and patterns from setMissingStyleImageResolver, which can also be async.

    Mapbox GL JS

    map.on('styleimagemissing', (e) => {
      map.addImage(e.id, generateImage(e.id));
    });

    MapLibre GL JS

    map.setMissingStyleImageResolver((id) => {
      map.addImage(id, generateImage(id));
    });

Mobile apps

MapLibre Native descends from Mapbox's earlier native SDKs, before their v10 redesign, so code written for those older versions is the closest match.

All MapLibre SDKs are on SDKs, with install snippets on Get started.

Frameworks and plugins

Several MapLibre projects started as forks of Mapbox ones, and keep a familiar API.

Mapbox services, and options with MapLibre

For each Mapbox product, the open-source and hosted options listed on this site. Mapbox's own services remain an option too, within its terms.

How the features compare

Both libraries have grown in their own directions since 2020, and neither is a superset of the other. Here is where they match and where they differ today.

Terms to know

If you keep using Mapbox services with MapLibre, these are the terms Mapbox publishes about that, quoted from Mapbox's own documents. They can change, so read the current version before you ship.

• Mapbox documents how to use its tile APIs and services in MapLibre GL JS.

  Because it shares the same API surface and style format, it integrates with Mapbox raster and vector tile APIs, and with most Mapbox services, using familiar patterns.

  Source ↗

• Mapbox GL JS v2 and later is licensed under the Mapbox Terms of Service for use with Mapbox products, while v1.13 and earlier remain under the BSD 3-Clause license.

  The software and files in this repository (collectively, "Software") are licensed under the Mapbox TOS for use only with the relevant Mapbox product(s) listed at www.mapbox.com/pricing.

  Source ↗

• Mapbox's attribution guide asks for the Mapbox logo and attribution when Mapbox maps are shown with another open-source library.

  If you are using Mapbox maps with another open source library, like Leaflet or OpenLayers, the Mapbox logo and attribution are still required.

  Source ↗

• Mapbox bills tile requests made through MapLibre and other third-party libraries per request under its Maps API, rather than as map loads.

  When consuming tiles through a third-party library (rather than Mapbox GL JS), tile requests are billed individually under the Maps API rather than being bundled into a map load.

  Source ↗

• Mapbox's Product Terms (section 3.36, last updated July 21, 2026) define a Mapbox Map by its content: any map that shows content from Mapbox APIs, such as map tiles, static map images, style files, glyphs or sprites (section 3.32).

  “Mapbox Map” means any map that includes any Licensed Map Content (other than Data Products).

  Source ↗

• Mapbox's Geocoding API documentation limits the use of its responses to a Mapbox map.

  You may only use responses from the Geocoding API in conjunction with a Mapbox map.

  Source ↗

• Mapbox's Isochrone API documentation asks that results be displayed on a Mapbox map drawn with a Mapbox library or SDK.

  Results must be displayed on a Mapbox map using one of the Mapbox libraries or SDKs.

  Source ↗

• Mapbox's Map Matching API documentation has the same display requirement.

  Results must be displayed on a Mapbox map using one of the Mapbox libraries or SDKs.

  Source ↗

• The Product Terms (section 2.7.5) restrict POI results from Mapbox search to use with a Mapbox Map.

  Customer shall not use any POI Results (i) except in conjunction with a Mapbox Map

  Source ↗

• The Product Terms (section 2.11) limit styles made in or exported from Mapbox Studio to Studio or a Mapbox Map.

  For any style developed in or exported from Studio, Customer shall only use that style within Studio or on a Mapbox Map and not any other map design tool or non-Mapbox Map.

  Source ↗

• For mobile apps, the Product Terms (section 2.9.1) name Mapbox's Mobile SDKs as the exclusive way to access Mapbox services.

  Customer shall use the Mobile SDKs as Customer’s exclusive means of accessing the Service Offerings in mobile applications.

  Source ↗