matplotlib/matplotlib · error · ImportError

Failed to import tkagg backend. You appear to be using an ou

Error message

Failed to import tkagg backend. You appear to be using an outdated version of uv's managed Python distribution which is not compatible with Tk. Please upgrade to the latest uv version, then update Python with: `uv python upgrade --reinstall`

What it means

ImportError raised while importing the TkAgg backend when the underlying _tkagg extension import fails with the specific chained error ''_tkinter' has no attribute '__file__'' AND the running interpreter's real path contains '/uv/python'. That attribute error is the signature of old python-build-standalone distributions whose _tkinter is incompatible; matplotlib recognizes uv-managed Pythons and tells you to upgrade uv and reinstall its Python.

Source

Thrown at lib/matplotlib/backends/_backend_tk.py:39

    _Backend, FigureCanvasBase, FigureManagerBase, NavigationToolbar2,
    TimerBase, ToolContainerBase, cursors, _Mode, MouseButton,
    CloseEvent, KeyEvent, LocationEvent, MouseEvent, ResizeEvent)
from matplotlib._pylab_helpers import Gcf

try:
    from . import _tkagg
    from ._tkagg import TK_PHOTO_COMPOSITE_OVERLAY, TK_PHOTO_COMPOSITE_SET
except ImportError as e:
    # catch incompatibility of python-build-standalone with Tk
    cause1 = getattr(e, '__cause__', None)
    cause2 = getattr(cause1, '__cause__', None)
    if (isinstance(cause1, ImportError) and
            isinstance(cause2, AttributeError) and
            "'_tkinter' has no attribute '__file__'" in str(cause2)):

        is_uv_python = "/uv/python" in (os.path.realpath(sys.executable))
        if is_uv_python:
            raise ImportError(
                "Failed to import tkagg backend. You appear to be using an outdated "
                "version of uv's managed Python distribution which is not compatible "
                "with Tk. Please upgrade to the latest uv version, then update "
                "Python with: `uv python upgrade --reinstall`"
                ) from e
        else:
            raise ImportError(
                "Failed to import tkagg backend. This is likely caused by using a "
                "Python executable based on python-build-standalone, which is not "
                "compatible with Tk. Recent versions of python-build-standalone "
                "should be compatible with Tk. Please update your python version "
                "or select another backend."
                ) from e
    else:
        raise


_log = logging.getLogger(__name__)

View on GitHub (pinned to b379c1b69e)

Solutions

Upgrade uv (e.g. 'uv self update' or your package manager), then run 'uv python upgrade --reinstall' to get a Tk-compatible managed CPython
Interim workaround: set MPLBACKEND=Agg (or matplotlib.use('QtAgg')) so TkAgg is never imported
Alternatively use a system CPython (python.org installer / distro package) which ships working _tkinter

Example fix

# before (old uv-managed python)
$ uv run python plot.py  # ImportError: Failed to import tkagg backend ...

# after
$ uv self update
$ uv python upgrade --reinstall
$ uv run python plot.py

Defensive patterns

Strategy: fallback

Validate before calling

import os, sys

def tkagg_usable() -> bool:
    """Detect the broken uv-managed _tkinter before TkAgg import."""
    if '/uv/python' not in os.path.realpath(sys.executable):
        return True
    import tkinter
    try:
        tkinter._tkinter.__file__
        return True
    except AttributeError:
        return False

# usage: matplotlib.use('TkAgg' if tkagg_usable() else 'Agg')

Try / catch

try:
    import matplotlib
    matplotlib.use('TkAgg')
except ImportError as e:
    if 'tkagg' in str(e):
        import matplotlib
        matplotlib.use('QtAgg')  # Tk toolchain broken; use another backend
    else:
        raise

Prevention

Keep uv and its managed Pythons current: uv self update && uv python upgrade --reinstall
Run a startup probe of tkinter in uv environments before choosing interactive backends
Prefer backend-agnostic entry points (MPLBACKEND) so environments can override broken GUI toolkits

When it happens

Trigger: Using a uv-managed Python (uv venv / uv run, older uv) and selecting TkAgg: matplotlib.use('TkAgg'), plt.show() picking Tk, or matplotlib.get_backend() flows that import _backend_tk. The detection rewrites an opaque ImportError into an actionable uv-specific message.

Common situations: Projects adopting uv on Linux/macOS where Tk was previously used for plt.show(); CI images pinned to an old uv version; switching a Tk GUI script into a uv workspace for the first time.

Related errors

AI-assisted analysis of matplotlib/matplotlib@b379c1b69e (2026-08-21). Data as JSON: /api/errors/77334bd2ae3ee8be. Report an issue: GitHub.