Matplotlib Basemap deprecation & replacement by CartoPy

less than 1 minute read

Users of Matplotlib Basemap have long suffered a somewhat buggy API, that made cross-platform sharing of map plotting software a bit challenging at times. By 2017, Basemap deprecation was announced, with CartoPy designated as the Basemap replacement. Basemap is being minimally maintained for the sake of Python 2.7 users, and CartoPy is adding features to restore those not overlapping with Basemap. Instead of a massive multi-megabyte install, CartoPy downloads and caches shape files etc. as needed.

New users and new projects should be using PROJ.4 / GEOS-based CartoPy instead of Basemap.


CartoPy uses shapely and other easily available / automatically & seamlessly installed prereqs, unlike Basemap which could be a fight to get installed.

conda install cartopy


Note the zorder option of Matplotlib elements such as contourf. Higher number zorder is higher priority (on top). See for an example of zorder.


Notice how the syntax is much more intuitive than Basemap.

import cartopy
import cartopy.feature as cpf
from matplotlib.pyplot import figure, show

def main():

    ax = figure().gca(

    ax.add_feature(cpf.BORDERS, linestyle=':')
    ax.add_feature(cpf.LAKES,   alpha=0.5)

    ax.set_extent([-20, 60, -40, 40])

if __name__ == '__main__':

Further examples

Leave a Comment