# adjustText for Matplotlib Label Placement

> adjustText iteratively moves Matplotlib labels to reduce collisions with other labels and plotted data. It suits repeated scientific and engineering plots, but does not guarantee a collision-free or semantically optimal layout.

**Phlya/adjustText** — A small library for automatical adjustment of text position in matplotlib plots to minimize overlaps.

- Repository: https://github.com/Phlya/adjustText
- Website: https://adjusttext.readthedocs.io/
- Stars: 1,666 · Forks: 97
- Language: Jupyter Notebook
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/phlya-adjusttext

## What adjustText Changes in a Matplotlib Figure

adjustText addresses a specific readability problem in Matplotlib: labels attached to many points often collide with one another or with plotted marks. The coordinates and underlying data may still be correct, while the annotation layer remains difficult to read. This library does not replace Matplotlib or alter the plotted data. It adjusts text positions in a figure that already exists.

The intended users are Python developers producing point-based scientific and engineering visualizations. `setup.py` classifies the package under Matplotlib and scientific or engineering visualization, while the repository topics include graph, plotting, Python, text, and matplotlib. Its scope is annotation placement inside a Matplotlib figure rather than general document layout, text wrapping, or diagram routing.

That boundary matters when selecting the library. adjustText is not a general layout engine. If labels must follow domain rules, remain inside a fixed inset, or connect to points through specialized leaders, reducing collisions may not satisfy the full requirement. A chart with a small number of important labels may also be easier to position manually. adjustText is most useful when the same annotation pattern recurs across many generated figures.

## Iterative Placement Instead of Complete Layout Planning

The core approach described by the repository is iterative adjustment. The library moves existing text labels through repeated steps intended to minimize overlaps. This differs from a layout operation that determines every annotation's final position before the chart is rendered.

The apparent workflow begins with a Matplotlib figure, its plotted data, and its existing text annotations. The adjustText API then changes those text positions according to the algorithm and its configurable settings. The README does not document the collision geometry, objective function, iteration limit, stopping rule, or ordering of adjustments. It therefore supports describing the outcome as overlap minimization, but not a promise of globally optimal placement.

Several label collisions can also create conflicting targets. Moving one annotation can create space for another while reducing space elsewhere. Labels with different alignments and lengths may not fit neatly around a point. The README says the algorithm is configurable for complicated plots, but it does not enumerate those options in the installation or usage section. Users needing a particular strategy should inspect the current documentation and `docs/source/Examples.ipynb`.

The README offers a practical warning about geometry: smaller text and a somewhat larger figure often help. That advice recognizes that an annotation system has finite space. The adjustment algorithm cannot create room in a figure whose layout leaves none.

## Installing adjustText from PyPI or conda-forge

The README lists installation from PyPI as the basic option. Install the published package into the active Python environment with:

```bash
pip install adjustText
```

The package name in this command is `adjustText`. The README does not specify a minimum Python version or an operating-system constraint, so users should use the environment already required by their Matplotlib workflow and consult package metadata if exact compatibility matters.

For a conda environment, the documented command is:

```bash
conda install -c conda-forge adjusttext 
```

This command installs from the `conda-forge` channel and uses the package spelling `adjusttext`. That spelling differs from the mixed-case command used with pip.

The README also provides an archive installation route:

```bash
pip install https://github.com/Phlya/adjustText/archive/master.zip
```

That URL targets the repository's `master` branch rather than a numbered PyPI release. It can introduce a different code state from the published package, so a project that needs repeatable environment setup should record which source it used.

## Finding and Following the First Annotation Example

The repository points new users to its documentation and a notebook containing advanced examples. The README does not include a complete Python example with an import statement and adjustText function call. It would therefore be misleading to invent an API signature in a short tutorial. Readers should use the matching documentation and notebook instead.

Start with a normal Matplotlib plotting workflow and prepare the text annotations that need adjustment. Then open `docs/source/Examples.ipynb` and select an example corresponding to the figure being produced. The main documentation is hosted at `https://adjusttext.readthedocs.io/`.

Before applying a documented example, verify that its Matplotlib text objects and configuration correspond to the current plot. The package is backed by `numpy`, `matplotlib`, and `scipy`, as listed in `requirements.txt`, so the existing plotting environment remains part of the installation. Those requirements do not include version ranges in that file.

After running a documented example, inspect the figure at its intended display size. A layout that looks clear in a large notebook window may fail when the image is resized for a paper or report. The README's suggestion to reduce text size slightly and enlarge the figure is a useful first adjustment, not a guarantee that every annotation will be legible.

## Configuration Scope and Readability Limits

Configuration is most relevant when labels form several groups, points are tightly packed, or a default adjustment produces collisions elsewhere. The README says that the algorithm is highly configurable for complicated plots. It does not, however, provide a parameter list or explain the interaction between settings, so the documentation remains necessary for deciding which configuration applies.

The stated objective is overlap minimization. That is weaker than a guarantee that no text intersects any other artist. A label may need to cover data, move outside a preferred region, or remain too close to a point when every nearby position is occupied. adjustText does not claim to preserve user-defined coordinates, infer the semantic importance of labels, or optimize reading order.

It may also be the wrong tool for figures built around custom annotation classes or non-text elements. The repository describes its input as text position adjustment for Matplotlib and does not document compatibility with every custom artist. A layout whose labels are drawn later, reconstructed after adjustment, or converted to images may need a different integration.

Downstream rendering introduces another boundary. Font metrics, backend behavior, and export dimensions can change the space available to text. The repository does not document guarantees across those conditions. Visual inspection of the final export is therefore more informative than judging placement only in the development notebook.

## textalloc, ggrepel, and Manual Annotation Choices

The README names `textalloc` as an alternative and says that adjustText was inspired by the R package `ggrepel` for `ggplot2`. It does not provide an algorithm comparison, feature matrix, or statement that either project has the same plotting integration. Readers comparing them need to inspect each project's own documentation rather than infer API compatibility from the names.

The concrete difference presented for adjustText is its Matplotlib context. It iteratively adjusts text in an existing Matplotlib figure. A tool designed for automatic text allocation may address a different stage or use different layout rules, but the README does not specify those details for `textalloc`.

Manual placement offers direct control over small figures. It is often practical when only a few labels carry special significance or when their locations are fixed by editorial requirements. Its weakness is repetition: coordinates may need to be revisited whenever data or figure dimensions change.

adjustText reduces that manual iteration by transforming existing annotations after plotting. It does not decide what each label should communicate. Users must still choose labels, styling, figure dimensions, and any positions that are fixed for semantic reasons.

## Release History, MIT Licensing, and Upgrade Work

The repository is not archived, and the last push was on 2026-06-08. Recent releases include v1.4.0 on 2026-06-08, v1.3.0 on 2024-10-31, and v1.2.0 on 2024-06-27. These dates document recent project activity, but they are not evidence that every API remains unchanged or that releases follow a fixed schedule.

`setup.py` declares the package as `adjustText` and identifies its license as MIT. The repository also contains a `LICENSE` file. This is the project's declared licensing information. It does not replace reviewing terms for Matplotlib, SciPy, NumPy, documentation assets, or figures used in a particular publication.

The repository does not provide a migration guide or compatibility matrix in its README. Upgrading may therefore require checking changes in the current adjustText API and rerunning representative Matplotlib examples. A numerical or plotting dependency update can also affect rendered label geometry even when adjustText itself remains unchanged.

`requirements.txt` contains `numpy`, `matplotlib`, and `scipy` without version constraints. Environments intended for reproducible figures should preserve the actual resolved versions used during validation. The absence of bounds in that file is relevant when planning an upgrade or rebuilding an old notebook.

## Conclusion

adjustText is a sensible choice for Matplotlib users who repeatedly produce plots with crowded annotations and want iterative overlap reduction without implementing label placement themselves. It is less suitable for layouts that require deterministic coordinates, domain-specific label placement, or guaranteed collision-free output. Check the current documentation and `docs/source/Examples.ipynb` for the supported API, then confirm the result at the figure size and export resolution used for publication.

## FAQ

### How do I install adjustText for Matplotlib?

The README documents `pip install adjustText` for PyPI and `conda install -c conda-forge adjusttext` for conda. It also lists a direct installation command for the repository's `master` archive.

### Does adjustText guarantee that labels will not overlap?

No. The README describes iterative adjustment intended to minimize overlaps. It does not claim collision-free placement, especially for dense figures or labels with limited nearby space.

### Where are advanced adjustText examples documented?

The README points to `docs/source/Examples.ipynb` for advanced examples and to `https://adjusttext.readthedocs.io/` for the main documentation. The README itself does not show a complete function-call example.

## Sources

- [License: MIT](https://github.com/Phlya/adjustText/blob/master/LICENSE)
- [Phlya/adjustText on GitHub](https://github.com/Phlya/adjustText)
- [Project website](https://adjusttext.readthedocs.io/)
- [README](https://github.com/Phlya/adjustText/blob/master/README.md)
- [Releases](https://github.com/Phlya/adjustText/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/phlya-adjusttext