Install & Compatibility
Where this runs
tested against v1.4.0 · 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 3.336s · 319.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 11.5s · import 3.220s · 306MB
322MB installed
● package 322MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
adjust_text
✓ from adjustText import adjust_text
The primary function for adjusting text positions.
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()
Debug
Known issues
breakingVersion 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.fixRefer 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.
affects: <1.0.0
gotchaIt 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.fixEnsure `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.
affects: All versions
gotchaThe `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.fixUpgrade `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.
affects: <1.2.0 (with NumPy >= 2.0)
gotchaVersion 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.fixIf 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.
affects: >=1.3.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'adjusttext'
The 'adjusttext' module is not installed in the Python environment.
fixInstall the module using pip: 'pip install adjusttext'.
ImportError: No module named 'adjustText'
The module name is case-sensitive; 'adjustText' is incorrect.
fixUse the correct import statement: 'import adjusttext'.
ImportError: cannot import name 'adjust'
Attempting to import a non-existent 'adjust' function from 'adjusttext'.
fixUse the correct import statement: 'from adjusttext import adjust_text'.
TypeError: 'Annotation' object is not iterable
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.
fixCollect 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)`.
AttributeError: 'Axes3DSubplot' object has no attribute 'axesPatch'
The `adjusttext` library does not natively support 3D Matplotlib axes (`Axes3DSubplot`) as it relies on properties and methods specific to 2D axes.
fixAdjusttext 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.
Upgrade
Version history
1.4.0latest on PyPI · released Jun 8, 2026
Audit
Dependencies
matplotlibrequiredCore functionality for plotting and text objects.
numpyrequiredUsed for numerical operations and array handling; v1.2.0 introduced specific compatibility for NumPy 2.0.
scipyrequiredListed as a required dependency on PyPI, likely for underlying numerical algorithms.