Add a hint to update uv when a managed Python download is not found #17461

originell · 2026-01-14T11:59:17Z

Summary

When a project requests a newer Python version than the current UV version knows about, the existing error message isn't all that useful. Suggesting updating uv seems like a good hint for humans (and future LLM overlords) alike.

I just ran into this with some colleagues of mine. I upgraded a project to 3.14. They pulled and did a uv sync, but it failed. It turned out that their uv installation was at 0.5. Running a uv self update to update to 0.9.x made it work again.

Before:

error: No interpreter found for Python ==3.14.* in managed installations or search path

After:

error: No interpreter found for Python ==3.14.* in managed installations or search path

hint: No Python download is available for Python 3.14. This version might be newer than your uv. Update uv and retry.

The current idea for the hint does not explicitly mention running uv self update. That's because I felt like this wouldn't be a good idea due to the various ways uv could be installed. If you say uv self update is always safe, I'd be happy to adjust the hint and explicitly mention that command.

Test Plan

cargo nextest as laid out in the contributing docs.

originell · 2026-01-14T13:21:43Z

note: initial ci run rightfully discovered an error in my snapshot. i updated that. the new failure doesn't seem to be related to my code. if it is, pls let me know and i'll adjust :) i'm not too familiar with the uv codebase and rust in general

EliteTK · 2026-01-14T13:17:58Z

crates/uv-python/src/installation.rs

+                    let request_suffix = match request {
+                        PythonRequest::Default | PythonRequest::Any => String::new(),
+                        _ => format!(" for {request}"),
+                    };


If the version request was for Default or Any and we're down this path then something else is likely broken and we should just not show this hint.

that makes sense. thanks for that! I changed it in the latest commit

EliteTK · 2026-01-14T13:29:24Z

crates/uv-python/src/installation.rs

+                        _ => format!(" for {request}"),
+                    };
+                    return Err(err.with_missing_python_hint(format!(
+                        "No Python download is available{request_suffix}. This version might be newer than your uv. Update uv and retry."


This should say something closer to:

"This version of uv is unaware of a managed Python download for {request}. Consider updating uv if the requested version is newer."

Or something like that, I'm not 100% on the wording.

"no ... is available" implies it's unavailable which we're contradicting by suggesting

I get where you are going with this. I added another suggestion to the code. What do you think about:

This uv release may not support managed Python 3.100 yet. Update uv and retry.

I am not sure about "support" there but maybe @zanieb can advise on this detail before you make any further changes. I don't want to end up being overly nitpicky here.

True. "Support" might be too strong of a word here.

I don't think you are overly picky. Words are important.

I'll also sit some more on this. :)

EliteTK · 2026-01-14T13:31:34Z

crates/uv/tests/it/sync.rs

+    let mut filters = context.filters();
+    if cfg!(windows) {
+        filters.push((
+            "managed installations, search path, or registry",
+            "managed installations or search path",
+        ));
+    }


Use .with_filtered_python_sources() on the context instead. i.e. let context = TestContext::new_with_versions(&["3.12"]).with_managed_python_dirs().with_filtered_python_sources().

Then you can drop this.

crates/uv/tests/it/sync.rs

Co-authored-by: Zanie Blue <contact@zanie.dev>

EliteTK

👍 Thanks!

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [astral-sh/uv](https://github.com/astral-sh/uv) | patch | `0.9.24` → `0.9.26` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>astral-sh/uv (astral-sh/uv)</summary> ### [`v0.9.26`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0926) [Compare Source](astral-sh/uv@0.9.25...0.9.26) Released on 2026-01-15. ##### Python - Add CPython 3.15.0a5 ##### Enhancements - Add a hint to update uv when a managed Python download is not found ([#17461](astral-sh/uv#17461)) - Improve cache initialization failure error message ([#17469](astral-sh/uv#17469)) - Improve error message for abi3 wheels on free-threaded Python ([#17442](astral-sh/uv#17442)) - Add support for `--no-sources-package` ([#14910](astral-sh/uv#14910)) ##### Preview features - Add `METADATA.json` and `WHEEL.json` in uv build backend ([#15510](astral-sh/uv#15510)) - Add support for GCS request signing ([#17474](astral-sh/uv#17474)) - Adjust the process ulimit to the maximum allowed on startup ([#17464](astral-sh/uv#17464)) ##### Bug fixes - Lock to avoid concurrent refresh of pyx tokens ([#17479](astral-sh/uv#17479)) ##### Documentation - Add linting and formatting instructions to the CONTRIBUTING guide ([#17470](astral-sh/uv#17470)) - Avoid rendering `pyproject.toml` examples for more system-level settings ([#17462](astral-sh/uv#17462)) ### [`v0.9.25`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0925) [Compare Source](astral-sh/uv@0.9.24...0.9.25) Released on 2026-01-13. ##### Python - Add CPython 3.15.0a4 - Upgrade Tcl/Tk used by CPython to 9.0 ##### Enhancements - Add `--compile-bytecode` to `uv python install` and `uv python upgrade` to compile the standard library ([#17088](astral-sh/uv#17088)) - Allow disabling `exclude-newer` per package ([#16854](astral-sh/uv#16854)) - Broadcast `WM_SETTINGCHANGE` on `uv tool update-shell` ([#17404](astral-sh/uv#17404)) ##### Preview features - Detect workspace from `uv run` target ([#17423](astral-sh/uv#17423)) ##### Bug fixes - Avoid unwrapping size for file responses ([#17434](astral-sh/uv#17434)) - Use keyring authentication when retrieving `tool@latest` version ([#17448](astral-sh/uv#17448)) - Use latest Pyodide version for each python version ([#17372](astral-sh/uv#17372)) - Improve trampoline file handle closing ([#17374](astral-sh/uv#17374)) - Fix error message when installing musl python on armv7 ([#17213](astral-sh/uv#17213)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

Improve unmanaged version error message.

25fb48a

konstin requested a review from zanieb January 14, 2026 12:00

Adjust unmanaged version error message snapshot test for windows

4d1a3fa

EliteTK reviewed Jan 14, 2026

View reviewed changes

originell added 2 commits January 14, 2026 16:07

No downloads enabled but Requesting::Any or Default should be an error.

55c2dc7

Improve up update hint wording and snapshot testing

2c06d41

zanieb reviewed Jan 14, 2026

View reviewed changes

crates/uv/tests/it/sync.rs Outdated Show resolved Hide resolved

zanieb added the error messages Messaging when something goes wrong label Jan 14, 2026

originell and others added 3 commits January 15, 2026 08:31

Use zanibs text for uv update hinting

252eaa5

Co-authored-by: Zanie Blue <contact@zanie.dev>

Align test with updated hint wording.

acad04e

Pleasing the clippy overlord.

33654c3

EliteTK changed the title ~~Add actionable hint to unmanaged version error message~~ Hint to update uv when managed Python download is not found during uv sync Jan 15, 2026

EliteTK changed the title ~~Hint to update uv when managed Python download is not found during uv sync~~ Add a hint to update uv when managed Python download is not found during uv sync Jan 15, 2026

EliteTK approved these changes Jan 15, 2026

View reviewed changes

EliteTK changed the title ~~Add a hint to update uv when managed Python download is not found during uv sync~~ Add a hint to update uv when a managed Python download is not found Jan 15, 2026

EliteTK merged commit db7d1a2 into astral-sh:main Jan 15, 2026
75 checks passed

EliteTK mentioned this pull request Jan 15, 2026

Make uv pip compile attempt to download a specified --python-version if it can. #17249

Merged

originell deleted the fix/python-download-hint branch January 15, 2026 10:48

BrewTestBot mentioned this pull request Jan 15, 2026

uv 0.9.26 Homebrew/homebrew-core#263018

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add a hint to update uv when a managed Python download is not found #17461

Add a hint to update uv when a managed Python download is not found #17461

originell commented Jan 14, 2026 •

edited

Loading

Uh oh!

originell commented Jan 14, 2026

Uh oh!

EliteTK Jan 14, 2026

Uh oh!

originell Jan 14, 2026

Uh oh!

EliteTK Jan 14, 2026

Uh oh!

originell Jan 14, 2026

Uh oh!

EliteTK Jan 14, 2026

Uh oh!

originell Jan 14, 2026

Uh oh!

EliteTK Jan 14, 2026

Uh oh!

originell Jan 14, 2026

Uh oh!

Uh oh!

EliteTK left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Add a hint to update uv when a managed Python download is not found #17461

Add a hint to update uv when a managed Python download is not found #17461

Conversation

originell commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Uh oh!

originell commented Jan 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

EliteTK left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

originell commented Jan 14, 2026 •

edited

Loading