---
id: adjusttext
version: "1.4.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# adjustText — Iteratively adjust text position in matplotlib plots to minimize overlaps

License: permissive · Maintenance: active · Downloads: 1.2M/mo

## What it is and what it does

adjustText solves the common problem of overlapping text labels on matplotlib plots by iteratively repositioning them to minimize collisions. When plotting multiple labeled points, the default matplotlib text placement often results in unreadable overlaps; this package automates the tedious manual repositioning work by applying an algorithm that moves labels away from each other and data points while keeping them visually associated with their targets.

The package works as a post-processing step on an existing matplotlib figure: you create your plot normally, pass the text objects to adjustText's main function, and it adjusts their positions. It requires only numpy, matplotlib, and scipy as dependencies and is designed to work well with minimal configuration, though the algorithm is highly configurable for complex cases. The library is inspired by ggrepel for R and offers a simpler alternative to manual label placement.

Use it for:

- Scatter plots with many labeled data points where default text placement causes heavy overlap
- Scientific figures with annotations that need automatic repositioning to improve readability
- Multi-point graphs where manual label adjustment would be time-consuming and error-prone
- Publication-ready plots requiring clean, non-overlapping label layouts without manual tweaking

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Automatically repositions text labels on matplotlib plots to minimize overlaps with other labels and data points using iterative adjustment.

Yes. Low install friction, permissive MIT license, active maintenance, no known vulnerabilities, and solves a genuine matplotlib usability problem. Install if you regularly create labeled plots and want to avoid manual label repositioning.

## Install

pip install adjusttext
uv add adjusttext
poetry add adjusttext

## Installing adjustText

Before you install: Low friction install with three common scientific dependencies (numpy, matplotlib, scipy). Actively maintained with recent releases; repository shows 1660 stars and current activity.

License in practice: MIT license permits use in proprietary and open-source projects with minimal restrictions; attribution required but no copyleft obligations.

Quickstart:

pip install adjustText

import matplotlib.pyplot as plt
from adjustText import adjust_text

plt.scatter([1, 2, 3], [1, 2, 3])
texts = [plt.text(x, y, f'label{i}') for i, (x, y) in enumerate([(1,1), (2,2), (3,3)])]
adjust_text(texts)
plt.show()

Verify before relying:

- Whether the algorithm's performance scales well with very large numbers of labels (hundreds or thousands)
- Specific configuration options available for tuning label placement behavior on complex plots

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 1.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

matplotlib label overlap removal, automatic text placement matplotlib, prevent overlapping labels plots, label positioning matplotlib, text annotation adjustment, matplotlib label collision detection, smart label placement, matplotlib-plugin, label-placement, visualization

[View on SkillFed](https://skillfed.io/packages/adjusttext) · [View on PyPI](https://pypi.org/project/adjusttext/)