Merge pull request #30486 from geofft/python-build-standalone-tkinter-doc

tacaswell · web-flow · commit c6557c6b04a1 · 2025-08-29T17:30:11.000-04:00
doc: Update warnings about python-build-standalone
diff --git 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
@@ -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 <optional_dependencies>`,
-           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 <optional_dependencies>`, 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`
