matplotlib-label-lines

0.8.1 verified Fri May 01 auth: no python

Label lines in matplotlib by adding text annotations near specified line segments. Version 0.8.1, supports Python >=3.9. Release cadence is low, no major updates in recent years.

pip install matplotlib-label-lines

Common errors

error ModuleNotFoundError: No module named 'labellines' ↓

cause Attempted import with wrong name (e.g., 'matplotlib_label_lines' or 'labellines' misspelled).

fix

Install via pip and use: from labellines import labelLines

error ImportError: cannot import name 'labelLines' from 'labellines' ↓

cause Older version of the library (before 0.6.0) used a different function name or the module is not installed correctly.

fix

Upgrade to latest version: pip install --upgrade matplotlib-label-lines

error KeyError: 'label' when calling labelLines ↓

cause One or more lines in the collection do not have a label set (label is empty or None).

fix

Set label for each line: plt.plot(x, y, label='my line') or pass lines with labels only.

Warnings

gotcha labelLines uses the line's label for text; if no label is set, it silently skips the line. ↓

fix Ensure every line you want labeled has a label string set via the 'label' parameter in plot.

gotcha labelLines positions labels based on the data range; if x or y data is not sorted, label placement may be unexpected. ↓

fix Sort your data before plotting or use labelLine for manual control.

deprecated In matplotlib 3.7+, get_lines() returns an immutable sequence; modifying the returned list is no longer possible. ↓

fix No change needed for labeling, but do not attempt to mutate ax.get_lines() directly.

gotcha The 'xvals' parameter expects x-coordinate values in data space; if you pass fractional axes coordinates, labels will be misplaced. ↓

fix Use data coordinates for xvals, or convert using ax.transData.transform().

Imports

labelLines
wrong
```
import labelLines
```
correct
```
from labellines import labelLines
```
Module name is 'labellines' (no spacing), function is labelLines.

labelLine

wrong

from labellines import label_lines

correct

from labellines import labelLine

Function is camelCase, not snake_case.

Quickstart

Basic example: plot three lines and label them with automatic positioning.

import matplotlib.pyplot as plt
import numpy as np
from labellines import labelLines

x = np.linspace(0, 1, 100)
fig, ax = plt.subplots()
for i in range(1, 4):
    ax.plot(x, x**i, label=f'$x^{i}$')
labelLines(ax.get_lines())
plt.show()