Skip to content

Documentation Home

matplotlib_map_utils logo

Introduction

matplotlib_map_utils is a package that that assists with the creation of maps using matplotlib.

As of v4.x (the current version), this includes the ability to easily create three common map elements:

  • North arrows, which automatically point to true north,

  • Scale bars, available in different styles and automatic unit conversion, and

  • Inset maps, including both detail and extent-style plots.

The three elements listed above are all intended to be high-resolution, easily modifiable, and context-aware relative to your specific plot.

This package also contains a single utility object:

  • USA, a class that helps filter for states and territories within the USA based on given characteristics, used primarily for building queries based on FIPS codes or names.

Together, these allow for the (relatively) easy creation of a map such as the following:

Map with all common elements added

Installation

This package is available on PyPi, and can be installed like so:

pip install matplotlib-map-utils

uv add matplotlib-map-utils

The requirements for this package are:

  • python >= 3.10 (due to the use of the pipe operator to concatenate dictionaries and types)

  • matplotlib >= 3.9 (might work with lower versions but not guaranteed)

  • cartopy >= 0.23 (due to earlier bug with calling copy() on CRS objects)

  • pydantic >= 2.13.3 (for type validation; might work with older versions, open an issue if you have questions)

Guides

For a primer on how to import the package and use the primary functions and methods to create elements, see the Quick Start guide.

Each part of the package also has a dedicated page that lays out usage and customisation options in more detail:

Finally, the Package Information page provides additional context around the development of and overall structure of the package.