From 25a97fd721edeee7ef2916cdbb79e050187f3d11 Mon Sep 17 00:00:00 2001 From: Thomas A Caswell Date: Fri, 29 Aug 2025 17:30:11 -0400 Subject: [PATCH] Backport PR #30486: doc: Update warnings about python-build-standalone --- doc/install/index.rst | 19 ++++++++++++++----- doc/install/quick_install.inc.rst | 17 ++++++++--------- 2 files changed, 22 insertions(+), 14 deletions(-) diff --git a/doc/install/index.rst b/doc/install/index.rst index eb5e02f98868..429e4bdaf60d 100644 --- a/doc/install/index.rst +++ b/doc/install/index.rst @@ -28,11 +28,20 @@ precompiled wheel for your OS and Python. .. note:: - The following backends work out of the box: Agg, ps, pdf, svg - - Python is typically shipped with tk bindings which are used by - TkAgg. Notably, python-build-standalone – used by ``uv`` – does - not include tk bindings that are usable by Matplotlib. + The following non-interactive backends work out of the box: Agg, + ps, pdf, svg + + The TkAgg interactive backend also typically works out of the box. + It requires Tk bindings, which are usually provided via the Python + standard library's ``tkinter`` module. On some OSes, you may need + to install a separate package like ``python3-tk`` to add this + component of the standard library. + + Some tools like ``uv`` make use of Python builds from the + python-build-standalone project, which only gained usable Tk + bindings recently (August 2025). If you are having trouble with the + TkAgg backend, ensure you have an up-to-date build, e.g. ``uv self + update && uv python upgrade --reinstall``. For support of other GUI frameworks, LaTeX rendering, saving animations and a larger selection of file formats, you can diff --git a/doc/install/quick_install.inc.rst b/doc/install/quick_install.inc.rst index 2e75b332f6ed..0604a3c8fe75 100644 --- a/doc/install/quick_install.inc.rst +++ b/doc/install/quick_install.inc.rst @@ -29,20 +29,19 @@ .. warning:: - If you install Python with ``uv`` then the ``tkagg`` backend - will not be available because python-build-standalone (used by uv - to distribute Python) does not contain tk bindings that are usable by - Matplotlib (see `this issue`_ for details). If you want Matplotlib - to be able to display plots in a window, you should install one of - the other :ref:`supported GUI frameworks `, - e.g. + uv usually installs its own versions of Python from the + python-build-standalone project, and only recent versions of those + Python builds (August 2025) work properly with the ``tkagg`` backend + for displaying plots in a window. Please make sure you are using uv + 0.8.7 or newer (update with e.g. ``uv self update``) and that your + bundled Python installs are up to date (with ``uv python upgrade + --reinstall``). Alternatively, you can use one of the other + :ref:`supported GUI frameworks `, e.g. .. code-block:: bash uv add matplotlib pyside6 - .. _this issue: https://github.com/astral-sh/uv/issues/6893#issuecomment-2565965851 - .. tab-item:: other :ref:`install-official`