{"record":{"id":"77334bd2ae3ee8be","repo":"matplotlib/matplotlib","slug":"failed-to-import-tkagg-backend-you-appear-to-be-u","errorCode":null,"errorMessage":"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`","messagePattern":"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`","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"lib/matplotlib/backends/_backend_tk.py","lineNumber":39,"sourceCode":"    _Backend, FigureCanvasBase, FigureManagerBase, NavigationToolbar2,\n    TimerBase, ToolContainerBase, cursors, _Mode, MouseButton,\n    CloseEvent, KeyEvent, LocationEvent, MouseEvent, ResizeEvent)\nfrom matplotlib._pylab_helpers import Gcf\n\ntry:\n    from . import _tkagg\n    from ._tkagg import TK_PHOTO_COMPOSITE_OVERLAY, TK_PHOTO_COMPOSITE_SET\nexcept ImportError as e:\n    # catch incompatibility of python-build-standalone with Tk\n    cause1 = getattr(e, '__cause__', None)\n    cause2 = getattr(cause1, '__cause__', None)\n    if (isinstance(cause1, ImportError) and\n            isinstance(cause2, AttributeError) and\n            \"'_tkinter' has no attribute '__file__'\" in str(cause2)):\n\n        is_uv_python = \"/uv/python\" in (os.path.realpath(sys.executable))\n        if is_uv_python:\n            raise ImportError(\n                \"Failed to import tkagg backend. You appear to be using an outdated \"\n                \"version of uv's managed Python distribution which is not compatible \"\n                \"with Tk. Please upgrade to the latest uv version, then update \"\n                \"Python with: `uv python upgrade --reinstall`\"\n                ) from e\n        else:\n            raise ImportError(\n                \"Failed to import tkagg backend. This is likely caused by using a \"\n                \"Python executable based on python-build-standalone, which is not \"\n                \"compatible with Tk. Recent versions of python-build-standalone \"\n                \"should be compatible with Tk. Please update your python version \"\n                \"or select another backend.\"\n                ) from e\n    else:\n        raise\n\n\n_log = logging.getLogger(__name__)","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/matplotlib/matplotlib/blob/b379c1b69e012b142c0f496a52bcb30513802d72/lib/matplotlib/backends/_backend_tk.py#L21-L57","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before (old uv-managed python)\n$ uv run python plot.py  # ImportError: Failed to import tkagg backend ...\n\n# after\n$ uv self update\n$ uv python upgrade --reinstall\n$ uv run python plot.py","handlingStrategy":"fallback","validationCode":"import os, sys\n\ndef tkagg_usable() -> bool:\n    \"\"\"Detect the broken uv-managed _tkinter before TkAgg import.\"\"\"\n    if '/uv/python' not in os.path.realpath(sys.executable):\n        return True\n    import tkinter\n    try:\n        tkinter._tkinter.__file__\n        return True\n    except AttributeError:\n        return False\n\n# usage: matplotlib.use('TkAgg' if tkagg_usable() else 'Agg')","typeGuard":null,"tryCatchPattern":"try:\n    import matplotlib\n    matplotlib.use('TkAgg')\nexcept ImportError as e:\n    if 'tkagg' in str(e):\n        import matplotlib\n        matplotlib.use('QtAgg')  # Tk toolchain broken; use another backend\n    else:\n        raise","preventionTips":["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"],"tags":["matplotlib","tkagg","tkinter","uv","python-build-standalone","toolchain-version","backend"],"backgroundTag":"tkinter-build-incompatibility","analyzedSha":"b379c1b69e012b142c0f496a52bcb30513802d72","analyzedAt":"2026-08-21T23:31:55.468Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}