Interactive data selection cursors for Matplotlib

0.7.1 · active · verified Sat Apr 11

mplcursors provides interactive data selection cursors for Matplotlib. It is inspired by mpldatacursor, offering a simplified API to add dynamic tooltips and annotations to plots, enhancing data exploration. The library is actively maintained, with its current version 0.7.1 released in March 2026.

Warnings

breaking The `index` attribute of a `Selection` object changed its path. It is now a direct attribute of `Selection`, not `Selection.target.index`.
Fix: Update code accessing `Selection.target.index` to `Selection.index`. `Selection.target.index` was deprecated in 0.5 and will be removed.
breaking When using the `MPLCURSORS` environment variable for global configuration, explicit registration in `mpl.rcParams['figure.hooks']` is now required.
Fix: Add `"mplcursors:install"` to `mpl.rcParams["figure.hooks"]` for global `MPLCURSORS` environment variable activation (requires Matplotlib>=3.7).
gotcha Annotations may not display correctly or disappear when using Matplotlib's animation blitting mode due to conflicts in artist drawing control.
Fix: Avoid using `mplcursors` with Matplotlib's blitting-enabled animations, or consider alternative approaches for interactivity in such scenarios.
gotcha Artists added to the figure *after* the initial figure draw (e.g., in interactive sessions or callbacks not using `pyplot` directly) may not be picked up by `mplcursors` by default.
Fix: Ensure all desired artists are present when `mplcursors.cursor()` is called, or explicitly pass a list of artists/axes to `mplcursors.cursor()` including dynamically added ones.
gotcha There have been known incompatibilities with specific Matplotlib versions (e.g., Matplotlib 3.10.3 was marked incompatible in `mplcursors` 0.7, and 3.7.1 in 0.5.3).
Fix: Consult the `mplcursors` changelog or documentation for specific Matplotlib compatibility requirements. Upgrade or downgrade Matplotlib if encountering issues.

Install

pip install mplcursors Install from PyPI
conda install conda-forge::mplcursors Install with Conda

Imports

cursor
```
from mplcursors import cursor
```
The primary function to enable interactive cursors on a plot or specific artists.

Quickstart

This basic example demonstrates how to create a simple Matplotlib plot and then apply `mplcursors.cursor()` to enable interactive data selection and draggable annotations on the plotted lines. A left click creates a draggable annotation, and a right click removes it.

import matplotlib.pyplot as plt
import numpy as np
import mplcursors

# Generate some data
data = np.outer(range(10), range(1, 5))
fig, ax = plt.subplots()
lines = ax.plot(data)

ax.set_title(
    "Click somewhere on a line.\nRight-click to deselect.\n" "Annotations can be dragged."
)

# Enable interactive cursors on the plotted lines
mplcursors.cursor(lines, hover=False) # hover=False means click to activate

plt.show()

view raw JSON →