Install & Compatibility
Where this runs
tested against v0.7.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 2.658s · 178.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 7.5s · import 2.558s · 170MB
181MB installed
● package 181MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cursor
✓ from mplcursors import cursor
The primary function to enable interactive cursors on a plot or specific artists.
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()
Debug
Known issues
breakingThe `index` attribute of a `Selection` object changed its path. It is now a direct attribute of `Selection`, not `Selection.target.index`.fixUpdate code accessing `Selection.target.index` to `Selection.index`. `Selection.target.index` was deprecated in 0.5 and will be removed.
affects: 0.5 and later
breakingWhen using the `MPLCURSORS` environment variable for global configuration, explicit registration in `mpl.rcParams['figure.hooks']` is now required.fixAdd `"mplcursors:install"` to `mpl.rcParams["figure.hooks"]` for global `MPLCURSORS` environment variable activation (requires Matplotlib>=3.7).
affects: 0.7 and later
gotchaAnnotations may not display correctly or disappear when using Matplotlib's animation blitting mode due to conflicts in artist drawing control.fixAvoid using `mplcursors` with Matplotlib's blitting-enabled animations, or consider alternative approaches for interactivity in such scenarios.
affects: All versions
gotchaArtists 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.fixEnsure 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.
affects: All versions
gotchaThere 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).fixConsult the `mplcursors` changelog or documentation for specific Matplotlib compatibility requirements. Upgrade or downgrade Matplotlib if encountering issues.
affects: Various, depending on `mplcursors` and `matplotlib` versions
Errors
Common errors & fixes
ImportError: No module named 'mplcursors'
The 'mplcursors' library is not installed in the Python environment.
fixInstall the library using pip: 'pip install mplcursors'.
AttributeError: module 'mplcursors' has no attribute 'cursor'
The 'mplcursors' module is not correctly imported or the function 'cursor' is not available.
fixEnsure correct import with 'import mplcursors' and verify the function's availability in the module.
TypeError: 'NoneType' object is not iterable
The 'mplcursors.cursor()' function is called with an invalid or NoneType argument.
fixPass a valid Matplotlib artist or list of artists to 'mplcursors.cursor()'.
ValueError: Invalid annotation_positions parameter
The 'annotation_positions' parameter in 'mplcursors.cursor()' is set incorrectly.
fixProvide a valid list of dictionaries with correct keys for 'annotation_positions'.
RuntimeError: Event loop is already running
Attempting to use 'mplcursors' in an environment where the event loop is already active, such as Jupyter Notebook.
fixUse '%matplotlib notebook' or '%matplotlib widget' in Jupyter Notebook to enable interactive plots.
Upgrade
Version history
0.7.1latest on PyPI · released Mar 18, 2026
Audit
Dependencies
matplotlibrequiredCore dependency for plotting, requires Matplotlib>=3.1.
pythonrequiredRequires Python version >=3.7.
numpyoptionalOften used with Matplotlib for data generation.