More descriptive error message for `uv run pythonx.xx` #12201

JWLee89 · 2025-03-16T12:12:47Z

Related Issue

Summary

Add meaningful message when user invokes uv with run python<valid-python-version>.

✅ "python", "python3", "python3.9", "python4", "python3.10", "python3.13.3", "python39" (yes, python39 might still be released in 100 years 😆 )
❌ "python3abc", "python3.12b3", "", "python-foo"

Contextual information added depending on whether the command was run inside of a uv project or not. See: https://github.com/astral-sh/uv/pull/12201/files#diff-423c3a82aab6dba4068dd7675391fc9328a66682131dbf2043e7847ab4ba8661R1092

Automated Tests

Added unit test for new functions created for parsing and validating python executable entered by user
TODO: Once specs are finalized through discussions in PR, will create integration tests if necessary

Need to Discuss

Invoking python via its patch version - E.g. python3.11.9 is invalid. However, uv supports uv run -p 3.11.9 python, which is why when we do the following:

uv run python3.11.9

We will get the following error:

error: Failed to spawn: `python3.11.9`
  Caused by: `python3.11.9` not available in the environment, which uses python `3.11.9`. Did you mean to search for a Python 3.11.9 environment with `uv run -p 3.11.9 python`?

Is this okay? If not, we need to define the specs in the PR here.

Supported python executable specs are defined as:

is stable version
is not post version

See:https://github.com/astral-sh/uv/pull/12201/files#diff-423c3a82aab6dba4068dd7675391fc9328a66682131dbf2043e7847ab4ba8661R1572-R1574

Would this be okay?
We can change the specs if needed. Lets discuss.

Manual Test

Case 1: run outside of project

Case where no project is created. Look for a python executable version that is not available in my local machine (in my case, it was python3.9)
Run cargo run -- run python3.9.3

error: Failed to spawn: `python3.9.3`
  Caused by: `python3.9.3` not available in the environment, which uses python `3.11.9`. Did you mean to search for a Python 3.9.3 environment with `uv run -p 3.9.3 python`?

Run cargo run -- run python3.9

error: Failed to spawn: `python3.9`
  Caused by: `python3.9` not available in the environment, which uses python `3.11.9`. Did you mean to search for a Python 3.9 environment with `uv run -p 3.9 python`?

Run cargo run -- run python3.11

Running `target/debug/uv run python3.11`
Python 3.11.9 (main, Apr  2 2024, 08:25:04) [Clang 15.0.0 (clang-1500.3.9.4)] on darwin
Type "help", "copyright", "credits" or "license" for more information.

Run cargo run -- run python3.11.9

 Running `target/debug/uv run python3.11.9`
error: Failed to spawn: `python3.11.9`
  Caused by: `python3.11.9` not available in the environment, which uses python `3.11.9`. Did you mean to search for a Python 3.11.9 environment with `uv run -p 3.11.9 python`?

IMPORTANT: Is this acceptable? Invoking python by its patch version is not supported, so this is the expected behavior, but we need to discuss whether this behavior is acceptable.

Case 2: run inside of project

Create project using uv init example-app

uv run python3.13

error: Failed to spawn: `python3.13`
  Caused by: `python3.13` not available in the project environment, which uses python `3.12.5`. Did you mean to change the environment to Python 3.13 with `uv run -p 3.13 python`?

uv run python3

uv run python3
Python 3.12.5 (main, Aug  6 2024, 19:08:49) [Clang 15.0.0 (clang-1500.3.9.4)] on darwin
Type "help", "copyright", "credits" or "license" for more information.

zanieb · 2025-04-16T15:36:33Z

Hey @JWLee89, thanks for the contribution! This looks like a nice improvement. We can provide some feedback to unblock adding tests.

zanieb · 2025-04-16T15:38:21Z

crates/uv/src/commands/project/run.rs

+            if err.kind() == std::io::ErrorKind::NotFound && is_python_executable(&executable) {
+                // Get version from python command string
+                // e.g. python3.12 -> "3.12" or "" if python version not specified. 
+                let version_part = executable.strip_prefix("python").unwrap_or("");


Should is_python_executable be python_executable_version -> Some(str) instead? Then you can avoid the unwrap_or?

Applied: 0cb2d5e

zanieb · 2025-04-16T15:40:09Z

I think the semantics make sense here. I wonder if we can reuse anything from the uv-python crate, but nothing obvious comes to mind.

jtfmumm · 2025-04-16T16:00:37Z

crates/uv/src/commands/project/run.rs

+            if err.kind() == std::io::ErrorKind::NotFound && is_python_executable(&executable) {
+                // Get version from python command string
+                // e.g. python3.12 -> "3.12" or "" if python version not specified. 
+                let version_part = executable.strip_prefix("python").unwrap_or("");


Maybe specified_version instead of version_part?

Applied: e4a2fa1

jtfmumm · 2025-04-16T16:04:31Z

crates/uv/src/commands/project/run.rs

+            "python4",
+            "python",
+            "python3.11.3",
+            "python39", // Still a valid executable, although likely a typo


Since this is likely a typo and we probably don't have to worry about the distant future at the moment, should we detect cases over 37 and treat them as typos? Not necessary for this PR though

I think this can be a good idea, especially since python version 37 will not likely be released anytime in the future while we are still alive 😆 .

Still I think we should carefully discuss this and come up with a reasonable spec before making any feature changes.

Would it be okay if I create a separate PR for this once we discuss and decide on specifications here?

zanieb · 2025-04-16T16:06:55Z

crates/uv/src/commands/project/run.rs

+/// - ❌ "python3abc", "python3.12b3", "", "python-foo"
+fn is_python_executable(executable_command: &str) -> bool {
+    executable_command
+        .strip_prefix("python")


Worth noting this isn't sufficient for Windows, where you'll have a .exe suffix (though versioned executables are not common there)

@zanieb

Thank you for the followup!

Windows handling logic

Good point! I don't a windows machine available to me right now, but my guess is that the access pattern for invoking python will be something like the following:

# versioned executable python3.11.exe # General python.exe

Would this be correct?

A simple approach could be also stripping suffix .exe. I don't think we should introduce complexity by checking whether the host is running windows unless this contextual information is already available without extra compute somewhere else.

Additional Possible Cases for Windows.

From some quick ChatGPT search, I found the following:

Command Notes

python After installing via the official installer, adds to PATH.

py Python launcher for Windows. Supports version flags like py -3.11.

python.exe Explicit executable, useful in scripts or batch files.

py -X.Y e.g., py -3.10 to launch a specific version via Python launcher.

pythonw.exe Launches Python without a console window (GUI apps).

Out of these items above, do we need to support the py launcher (E.g. py)? Just wanted to be sure :)

Edge cases

After thinking I just realized that people might invoke python using the following paths:

# absolute path /usr/bin/python3 # venv path /Users/username/repos/uv/venv/bin/python3.10

Should these kinds of absolute path specifications also be covered by this feature update?

CC: @jtfmumm

Thank you!

Applied here: e6a801d

Specs include:

strip .exe suffix

Support absolute path python. E.g. /Users/username/repos/uv/venv/bin/python3.10

Since spec was defined on the fly, might be good to review and discuss this together.

Thank you! 🙇

As I suspected quite some time ago (#6738 (comment)), it's problematic that we don't handle _every_ signal here. This PR adds handling for all of the Unix signals except `SIGCHLD`, `SIGIO`, and `SIGPOLL` which seem incorrect to forward. Also notable, we _cannot_ handle `SIGKILL` so if someone sends that to the PID instead of the PGID, they will leave dangling subprocesses. Instead, we could use `exec` and avoid this handling. However, we'd lose the ability to add nice error message on failure (e.g., as someone is trying to add in #12201) and, more critically, we'd need to figure out how to clean up resources properly (i.e., temporary directories) which currently happens on `Drop`. In the long-term, we'll probably want an option to use `exec` — but we'll need to figure out when to clean up resources or accept that they will dangle. This was last discussed in #3095 — discussion on that approach should continue there. A note on the implementation: I spent time time trying to write the handler using a tokio stream, so we could dynamically iterate over a list of signals instead of copy/pasting the implementation — I couldn't get it to work though and it didn't seem critical. Closes #12830

jtfmumm · 2025-04-24T16:15:05Z

I pushed some snapshot (integration) tests for a handful of cases.

I think we might want to update the error messages for uv run pythonX.X.X (the case you called out in your description). At least when it matches the patch version in use, it's a bit confusing. Though it's nice to have the rest of the message when it's not matched. But it seems like an opportunity to indicate that this is not expected usage. The first snapshot test I added captures this behavior.

JWLee89 · 2025-04-26T08:43:18Z

I pushed some snapshot (integration) tests for a handful of cases.

Thank you so much for adding the snapshot (integration) tests! 🙇
I will keep this in mind when working on future PRs to add integration tests when necessary.

I think we might want to update the error messages for uv run pythonX.X.X (the case you called out in your description). At least when it matches the patch version in use, it's a bit confusing. Though it's nice to have the rest of the message when it's not matched. But it seems like an opportunity to indicate that this is not expected usage. The first snapshot test I added captures this behavior.

I absolutely agree and thank you for bringing this up!
Applied: 9976500

I should have clarified about this point properly in this PR.
In my environment, I reproduced it with the following command:

uv run python3.13.2

Results:

`python3.13.2` not available in the virtual environment, which uses python `3.13.2`. Did you mean to search for a Python 3.13.2 environment with `uv run -p 3.13.2 python`?

Description of update

When users specify up to the patch version:

uv run python3.3.3

I updated so that if users specify up to the patch version. E.g. python3.12.x, we get a error message that tells users to either use uv run -p or use uv run without the patch version (see below).

error: Failed to spawn: `python3.3.3`
  Caused by: Please omit patch version. Try: `uv run python3.3`. Did you mean to search for a Python 3.3.3 environment with `uv run -p 3.3.3 python`?

However, if we omit patch version, we will get the following (same behavior as before):

error: Failed to spawn: `python3.3`
  Caused by: `3.3` not available in the virtual environment, which uses python `3.13.2`. Did you mean to search for a Python 3.3 environment with `uv run -p 3.3 python`?

Note: message is subject to discussion and I think after iterating together, we can come up with the finalized message soon :).
For now, I just want to emphasize that I implemented the logic to change the error message depending on whether patch version is omitted or not.

…rovided

JWLee89 mentioned this pull request Mar 16, 2025

Failed to spawn error with uv run python3.12 #11796

Open

JWLee89 force-pushed the issue-11796 branch 2 times, most recently from 0271bb7 to c363629 Compare March 16, 2025 12:42

charliermarsh assigned zanieb Mar 16, 2025

zanieb reviewed Apr 16, 2025

View reviewed changes

zanieb added the error messages Messaging when something goes wrong label Apr 16, 2025

jtfmumm self-assigned this Apr 16, 2025

jtfmumm reviewed Apr 16, 2025

View reviewed changes

zanieb reviewed Apr 16, 2025

View reviewed changes

JWLee89 added 7 commits April 19, 2025 14:59

feat: add function for checking if command is python executable

8e1a432

feat: Add meaningful message when attempting to invoke python using run

22f2e7a

fix: enable message to show for patch versions

8ce5035

feat: add support for different message depending on if project is found

a218c91

fix: run lint

f441817

fix: change message for project

11e94a8

docs: update docstring

286c99b

JWLee89 force-pushed the issue-11796 branch from 1991d43 to 286c99b Compare April 19, 2025 06:01

refactor: rename version_part to specified_version

e4a2fa1

JWLee89 force-pushed the issue-11796 branch from a040d02 to b650522 Compare April 20, 2025 07:27

refactor: update code to be more idiomatic

0cb2d5e

JWLee89 force-pushed the issue-11796 branch from cb6de44 to 0cb2d5e Compare April 20, 2025 07:31

feat: add support for .exe and absolute path python

e6a801d

JWLee89 requested review from zanieb and jtfmumm April 20, 2025 13:21

zanieb mentioned this pull request Apr 21, 2025

Forward additional signals to the child process in uv run #13017

Merged

konstin changed the title ~~Issue-11796: Provide more descriptive message for uv run pythonx.xx~~ Provide more descriptive message for uv run pythonx.xx Apr 24, 2025

konstin changed the title ~~Provide more descriptive message for uv run pythonx.xx~~ More descriptive error message for uv run pythonx.xx Apr 24, 2025

jtfmumm added 2 commits April 24, 2025 18:02

Add snapshot tests for running missing Python versions

0c6b069

snapshot tests fixes

73c5243

Ensure system Python isn't used in snapshot tests

7433028

JWLee89 force-pushed the issue-11796 branch 3 times, most recently from 489d8b2 to 87c1ad7 Compare April 26, 2025 09:08

feat: provide meaningful error message when python patch version is p…

9976500

…rovided

JWLee89 force-pushed the issue-11796 branch from f46efa0 to 9976500 Compare April 26, 2025 09:14

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

More descriptive error message for `uv run pythonx.xx` #12201

More descriptive error message for `uv run pythonx.xx` #12201

JWLee89 commented Mar 16, 2025 •

edited

Loading

zanieb commented Apr 16, 2025

zanieb Apr 16, 2025

JWLee89 Apr 20, 2025

zanieb commented Apr 16, 2025

jtfmumm Apr 16, 2025

JWLee89 Apr 19, 2025

jtfmumm Apr 16, 2025

JWLee89 Apr 19, 2025 •

edited

Loading

zanieb Apr 16, 2025 •

edited

Loading

JWLee89 Apr 19, 2025 •

edited

Loading

JWLee89 Apr 20, 2025

jtfmumm commented Apr 24, 2025

JWLee89 commented Apr 26, 2025 •

edited

Loading

Command	Notes
python	After installing via the official installer, adds to PATH.
py	Python launcher for Windows. Supports version flags like py -3.11.
python.exe	Explicit executable, useful in scripts or batch files.
py -X.Y	e.g., py -3.10 to launch a specific version via Python launcher.
pythonw.exe	Launches Python without a console window (GUI apps).

More descriptive error message for uv run pythonx.xx #12201

Are you sure you want to change the base?

More descriptive error message for uv run pythonx.xx #12201

Conversation

JWLee89 commented Mar 16, 2025 • edited Loading

Related Issue

Summary

Automated Tests

Need to Discuss

Manual Test

Case 1: run outside of project

Case 2: run inside of project

zanieb commented Apr 16, 2025

zanieb Apr 16, 2025

Choose a reason for hiding this comment

JWLee89 Apr 20, 2025

Choose a reason for hiding this comment

zanieb commented Apr 16, 2025

jtfmumm Apr 16, 2025

Choose a reason for hiding this comment

JWLee89 Apr 19, 2025

Choose a reason for hiding this comment

jtfmumm Apr 16, 2025

Choose a reason for hiding this comment

JWLee89 Apr 19, 2025 • edited Loading

Choose a reason for hiding this comment

zanieb Apr 16, 2025 • edited Loading

Choose a reason for hiding this comment

JWLee89 Apr 19, 2025 • edited Loading

Choose a reason for hiding this comment

Windows handling logic

Additional Possible Cases for Windows.

Edge cases

JWLee89 Apr 20, 2025

Choose a reason for hiding this comment

jtfmumm commented Apr 24, 2025

JWLee89 commented Apr 26, 2025 • edited Loading

Description of update

More descriptive error message for `uv run pythonx.xx` #12201

More descriptive error message for `uv run pythonx.xx` #12201

JWLee89 commented Mar 16, 2025 •

edited

Loading

JWLee89 Apr 19, 2025 •

edited

Loading

zanieb Apr 16, 2025 •

edited

Loading

JWLee89 Apr 19, 2025 •

edited

Loading

JWLee89 commented Apr 26, 2025 •

edited

Loading