Adjust Text Positions in Matplotlib Plots

1.3.0 verified Fri May 15 auth: no python

adjustText is a Python library that iteratively adjusts the position of text labels in Matplotlib plots to minimize overlaps with other labels, data points, and plot boundaries. It is currently at version 1.3.0 and has a regular release cadence, often addressing compatibility and performance improvements. The approach is inspired by the `ggrepel` package for R/ggplot2.

pip install adjustText

Common errors

error ModuleNotFoundError: No module named 'adjusttext' ↓

cause The 'adjusttext' module is not installed in the Python environment.

fix

Install the module using pip: 'pip install adjusttext'.

error ImportError: No module named 'adjustText' ↓

cause The module name is case-sensitive; 'adjustText' is incorrect.

fix

Use the correct import statement: 'import adjusttext'.

error ImportError: cannot import name 'adjust' ↓

cause Attempting to import a non-existent 'adjust' function from 'adjusttext'.

fix

Use the correct import statement: 'from adjusttext import adjust_text'.

error TypeError: 'Annotation' object is not iterable ↓

cause The `adjust_text` function expects a list of `matplotlib.text.Text` objects to adjust, but a single `matplotlib.text.Annotation` object (returned by `plt.annotate`) or a similar non-iterable object was passed directly.

fix

Collect all text objects (e.g., from plt.text or plt.annotate) into a list and pass the list to adjust_text. For plt.annotate, append the annotation object to a list; for plt.text, append the text object to a list. Example: texts = []; for i, txt in enumerate(labels): texts.append(ax.text(x[i], y[i], txt)); adjust_text(texts).

error AttributeError: 'Axes3DSubplot' object has no attribute 'axesPatch' ↓

cause The `adjusttext` library does not natively support 3D Matplotlib axes (`Axes3DSubplot`) as it relies on properties and methods specific to 2D axes.

fix

Adjusttext is not designed for 3D plots. Consider alternative methods for text placement in 3D plots or restructure your visualization to use 2D axes if adjusttext functionality is critical.

Warnings

breaking Version 1.0.0 introduced a 'new engine' with significant breaking API changes. Code written for versions prior to 1.0.0 may require updates to function correctly. ↓

fix Refer to the official documentation and examples for v1.0.0+ to update function calls and parameters, as the underlying adjustment logic and parameter handling changed.

gotcha It is crucial to call `adjust_text` as the very last step in your plotting code, after all other plot elements (especially those that might change axis limits) have been set. Failure to do so can lead to nonsensical or suboptimal text placement. ↓

fix Ensure `adjust_text(texts, ...)` is the final function call before `plt.show()` or saving the figure, after all `plt.plot`, `ax.set_xlim`, etc., have been executed.

gotcha The `v1.2.0` release provided specific compatibility for NumPy 2.0. Older versions of `adjustText` may encounter issues when used with NumPy 2.0 due to changes in NumPy's API and data type handling. ↓

fix Upgrade `adjustText` to version 1.2.0 or newer if you are using NumPy 2.0 or a compatible version. Consider pinning `adjustText` and `numpy` versions if encountering compatibility issues.

gotcha Version 1.3.0 introduced experimental logic to prevent arrow crossings. While intended to improve plots, this new feature might, in some complex scenarios, introduce unexpected behavior or performance implications. ↓

fix If unexpected behavior related to arrows is observed, consult the `adjustText` GitHub issues for similar reports or consider adjusting parameters related to arrow drawing (e.g., `min_arrow_len`, `arrowprops`). Report issues to the maintainers if the problem persists.

Install compatibility last tested: 2026-05-15 v1.3.0 (up to date)

python os / libc status wheel install import disk mem side effects

3.10 alpine (musl) wheel - 2.98s 318.9M 41.7M clean

3.10 slim (glibc) wheel 10.7s 2.18s 306M 41.7M clean

3.11 alpine (musl) wheel - 4.16s 342.1M 46.7M clean

3.11 slim (glibc) wheel 10.5s 3.81s 327M 46.7M clean

3.12 alpine (musl) wheel - 3.62s 326.6M 45.6M clean

3.12 slim (glibc) wheel 10.6s 3.79s 311M 45.6M clean

3.13 alpine (musl) wheel - 3.10s 325.2M 46.3M clean

3.13 slim (glibc) wheel 10.7s 3.38s 309M 46.3M clean

3.9 alpine (musl) wheel - 2.78s 317.2M 38.6M noisy

3.9 slim (glibc) wheel 12.5s 2.52s 310M 38.6M noisy

Imports

adjust_text
```
from adjustText import adjust_text
```
The primary function for adjusting text positions.

Quickstart

This example demonstrates how to create a scatter plot with overlapping text labels and then use `adjust_text` to automatically reposition them. Arrows are optionally added to connect the adjusted labels to their original data points.

import matplotlib.pyplot as plt
import numpy as np
from adjustText import adjust_text

# Generate some random data
np.random.seed(0)
x, y = np.random.random((2, 30))

# Create a matplotlib plot
fig, ax = plt.subplots()
ax.plot(x, y, 'o', markersize=5)

# Create text labels for each point
texts = []
for i, (xi, yi) in enumerate(zip(x, y)):
    texts.append(ax.text(xi, yi, f'Text{i}', ha='center', va='center'))

# Adjust text positions to minimize overlaps
adjust_text(texts, 
            arrowprops=dict(arrowstyle='-', color='gray', lw=0.5))

# Show the plot
plt.title('Adjusted Text Labels')
plt.xlabel('X-axis')
plt.ylabel('Y-axis')
plt.show()