{"id":4410,"library":"adjusttext","title":"Adjust Text Positions in Matplotlib Plots","description":"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.","status":"active","version":"1.3.0","language":"en","source_language":"en","source_url":"https://github.com/Phlya/adjustText","tags":["matplotlib","plotting","text","visualization","annotation"],"install":[{"cmd":"pip install adjustText","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core functionality for plotting and text objects.","package":"matplotlib","optional":false},{"reason":"Used for numerical operations and array handling; v1.2.0 introduced specific compatibility for NumPy 2.0.","package":"numpy","optional":false},{"reason":"Listed as a required dependency on PyPI, likely for underlying numerical algorithms.","package":"scipy","optional":false}],"imports":[{"note":"The primary function for adjusting text positions.","symbol":"adjust_text","correct":"from adjustText import adjust_text"}],"quickstart":{"code":"import matplotlib.pyplot as plt\nimport numpy as np\nfrom adjustText import adjust_text\n\n# Generate some random data\nnp.random.seed(0)\nx, y = np.random.random((2, 30))\n\n# Create a matplotlib plot\nfig, ax = plt.subplots()\nax.plot(x, y, 'o', markersize=5)\n\n# Create text labels for each point\ntexts = []\nfor i, (xi, yi) in enumerate(zip(x, y)):\n    texts.append(ax.text(xi, yi, f'Text{i}', ha='center', va='center'))\n\n# Adjust text positions to minimize overlaps\nadjust_text(texts, \n            arrowprops=dict(arrowstyle='-', color='gray', lw=0.5))\n\n# Show the plot\nplt.title('Adjusted Text Labels')\nplt.xlabel('X-axis')\nplt.ylabel('Y-axis')\nplt.show()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.2.0 (with NumPy >= 2.0)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.3.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}