ENH: Gracefully handle python-build-standalone ImportError with Tk #30394
Conversation
| isinstance(cause2, AttributeError) and | ||
| "'_tkinter' has no attribute '__file__'" in str(cause2)): | ||
|
|
||
| is_uv_python = "/uv/python" in (os.path.realpath(sys.executable)) |
There was a problem hiding this comment.
According to astral-sh/python-build-standalone#382, you might be able to use what uv uses: https://github.com/astral-sh/uv/blob/c25c800367a5f43069f1c9d778cfd5de1bcc54a6/crates/uv-python/python/get_interpreter_info.py#L639-L645 (i.e., sysconfig values).
There was a problem hiding this comment.
Is that more helpful?
I think we should catch the error, not exclude python-build-standalone per-se. If they'd fix the tk issue, our versions would directly work. On is_uv_python - I've explicitly tested for uv and tailored the error message, because I anticipate that'll by far the most route to trigger this, and I project that most uv users will not know what python-build-standalone is. So let's give them a uv-targeted error message.
There was a problem hiding this comment.
I didn't suggest excluding python-build-standalone, just detecting it differently.
There was a problem hiding this comment.
My point is I do not really care about python-build-standalone. The criterion is 1. does it raise the known error? And if so, is it a uv-install that I can point users to as the practical cause.
There was a problem hiding this comment.
If that's the case that you only care about uv, then the PR/commit title should be adjusted.
There was a problem hiding this comment.
Possibly my wording was not exactly precise.
The issue originates from the current way python-build-standalone is implmented. - So the PR title is justified.
Then there are two aspects to handling:
-
Detection: I want to detect the specific error and respond to that. - It's not helpful to detect python-build-standalone. They may improve to fix the error in the future. So issuing a warning/error purely on the fact that python-build-standalone is used would be presumptuous.
-
Error message: In the simplest case, we could just have the second error message
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. Please use another Python interpreter or select another backend.
(or if you want to be more affirmative explicitly test for python-build-standalone and remove the "likely"). However, the by-far most common way to obtain a python-build-standalone python is via
uv. But it's a technical detail ofuvand users are most likely not aware of it. So telling them, they have python-build-standalone is not helpful for fixing the issue. Therefore, I added theuvdetection to tell them that uv-provided python is not compatible.
There was a problem hiding this comment.
I am 👍 on doing the work to detect if it is uv.
|
FYI we're pretty close to fixing this in python-build-standalone - I think an error message is a good idea but it's probably not worth spending too much time working around this in detail (e.g., there's some code in Pillow that tries to work around this but doesn't quite handle things right, because that code path isn't tested, see astral-sh/python-build-standalone#129 (comment)). I'll hopefully come back soon with a request to change the wording from "not supported" to "please upgrade" :) |
|
Today's releases of uv and python-build-standalone should fix this issue. (Please let me know if they do not!) I still think a warning is a good idea because uv is not very proactive at upgrading its managed Python installations, but it should suggest upgrading your version of uv and your Python installations. For uv users, For python-build-standalone users who aren't getting it from uv, they will want today's release (20250808) or later. |
|
As Geoffrey noted, the canonical command we'll recommend to people is |
| "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. " | ||
| "Please use another Python interpreter or select another backend." |
There was a problem hiding this comment.
This should be updated too to mention that a newer python-build-standalone version will fix this - for users of other tools (Poetry, mise, Bazel rules_python, etc.) there should be a path forward without changing the tools and workflow they're using, though it's not practical or necessary to specifically document what exactly they should do to upgrade.
(Also, if you're editing this, small nit above - I would specifically say that you're using an outdated Python version, now that current uv-installed Python versions are compatible with Tk.)
| "Failed to import tkagg backend. You are using a uv-installed python " | ||
| "executable, which is not compatible with Tk. " | ||
| "Please update your python via: " | ||
| "`uv self update && uv python upgrade --reinstall`" |
There was a problem hiding this comment.
I think this is fine, but just so you're aware, uv self update won't be available for users that have installed uv through their package manager instead of the standalone installer. A more "general" solution would be to "upgrade to the latest version of uv then use uv python upgrade --reinstall"
|
I'm fine with the current text. I just wanted you to be aware it's not universal so you can make an informed decision. Here's a suggestion: https://github.com/matplotlib/matplotlib/pull/30394/files#r2294267220 |
Co-authored-by: Zanie Blue <contact@zanie.dev>
|
I believe the wording is now appropriate. |
Closes #30390.
I've tested this locally. I don't think there's a reasonable way to test this in CI unless we are actually willing to do a uv install for this. Mocking the exception does not bring any benefit in detecting whether the error has changed, so would be largely futile.