Adjust Text Positions in Matplotlib Plots

1.3.0 · active · verified Sun Apr 12

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.

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

pip install adjustText Install with pip

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()

view raw JSON →