Plotly is Switching to MapLibre

Written by: Nathan Drezner and Birk Skyum

TL;DR: Plotly is set to transition to MapLibre, bringing faster performance and increased stability.

With today's minor release of Plotly.js and Plotly.py, Plotly is deprecating our Mapbox traces and switching to MapLibre as the rendering library for all of our map-type charts.

When map traces first appeared in Plotly.js in 2016, they used Mapbox GL JS — this library has served those traces reliably over the past eight years. 

In 2020, Mapbox released v2.0, which changed the licensing terms for the software from the 3-clause BSD license to the current, custom Mapbox Terms of Service. As a result, Plotly hasn’t been able to update the underlying map renderer for map traces to the latest provided by Mapbox, and we’ve relied on a stagnant release for the last four years.

MapLibre is an independently-maintained fork of Mapbox GL JS v1.x, which ensures minimal changes in Plotly’s code. MapLibre also offers improved performance, better stability, long-term support, and an active roadmap of new features which we’ll be able to consider for inclusion into the Plotly charting libraries. Maplibre has organizational buy-in from organizations and companies including Amazon, Komoot, JawgMaps and more, and has historically strong governance and high-quality contributions.

Birk Skyum, a member of the MapLibre Governing Board and project maintainer, played an instrumental part in this change, providing the initial pull request and helping review the changes as members of the Plotly team continued the effort.

When is this launching?

Starting with the minor releases Plotly.js v2.35.0 and Plotly.py v5.24.0, Plotly developers can take advantage of MapLibre traces by updating trace names in Python projects or Dash apps from _mapbox to _map, for example changing px.scatter_mapbox to px.scatter_map. Developers can use the new traces starting today.

We intend this change to be invisible to most users. While the rendering library is changing, Open Street Maps remains the default tile service for Plotly maps, as it always has been.

This migration will take improvements to the MapLibre rendering system over the last four years and make them available to all Plotly users. We’ve been internally interested in switching to MapLibre as the rendering service for Plotly for several years.

You can see the version of Mapbox GL JS that powers Plotly’s Mapbox trace types:

And the contributions over the same period to MapLibre:

What’s changing for me?

We'd recommend following our migration guide for full instructions on how to use the new traces.

The MapLibre-powered traces in Plotly have new naming conventions, moving from names suffixed with _mapbox to names suffixed with _map. For example, px.scatter_mapbox will become px.scatter_map moving forward.

For developers switching to the new traces, keep an eye out for improved rendering performance, WebGL2 support, and over time, improved features in the Plotly map traces inherited from the MapLibre renderer, including projection support, globe views, terrain support, and support for modern mapping standards.

As always, we’re committed to backwards compatibility. The new MapLibre traces have a nearly identical API, with five changes to keep an eye out for:

1. Changing trace names from _mapbox to _map: As these traces are no longer powered by Mapbox, we’re dropping the Mapbox branding.
2. The layout.mapbox argument is now named layout.map, but has the same nested properties.
3. The mapbox_style argument is now map_style.
4. map_style options are changing. The style value allows developers to pick the format of their tiles, for example satellite, dark, or light. Today, our styles are provided by Mapbox, but moving forward we’ll be including open CARTO and ArcGIS styles in their stead. Developers using the built-in styles may notice slight differences in the look of their maps as a result. Using external styles remains supported with the same API.
5. Mapbox API keys are no longer required for Plotly-provided styles.

Developers using Plotly.js and Plotly.py will see this change roll out in several stages to ease the migration process:

1. Today, we’re issuing a release of our graphing libraries which introduces new traces using MapLibre and a deprecation notice for all Mapbox traces.
2. In the next major version of Plotly.js and Plotly.py (which developers can expect before EOY), we’ll be dropping all _mapbox traces in favor of the new map traces.

We’re taking this more cautious approach to ensure developers have time to migrate, review the new traces, and open any issues for our team to review before officially dropping support for Mapbox and moving entirely to the new MapLibre traces.

We also would encourage Plotly developers to join the MapLibre community and help participate in MapLibre’s collective, just as folks using our tooling today already participate in the Plotly community.

If you have any feedback or questions, please leave a note in our community forum or refer to our documentation. As always, if you experience any issues when migrating to these new traces, we encourage opening an issue in the Plotly.py or Plotly.js repositories, or, even better, opening a pull request. Our team is always happy to review and support developers contributing to Plotly projects.

Happy plotting!