Failed to spawn error with uv run python3.12

[gmsya]

Summary

Platform

mac

Version

uv 0.6.3 (a0b9f22 2025-02-24)

Python version

No response

[nkitsaini]

This is the intended behavior.

You are probably looking for uv run --python 3.12 python3 or uvx [email protected]. Both of these will work.

By default uv run <cmd>, will run the <cmd> as your shell would but by including libraries and binaries from virtual environment if present.

Since you already have python3.13 installed (outside of uv) it runs successfully.

Maybe we should include uv run --python 3.12 ... example in https://docs.astral.sh/uv/guides/install-python/.

[zanieb]

We could probably special-case this and provide a nice error message

[zanieb]

On a "not found" error, we can sniff for the command name (python3.12) and suggest the proper alternatives.

[JWLee89]

Hi @zanieb ,

If nobody is looking into this, do you mind if I try taking a look at this issue? Just getting my feet wet with uv.

(thinking of starting with this, because this does not seem to be a mission-critical issue, so getting a solution for this doesn't seem super high-priority).

Managed to reproduce with the following command:

MacBookPro uv % cargo run -- run python3.9 
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.76s
     Running `target/debug/uv run python3.9`
error: Failed to spawn: `python3.9`
  Caused by: No such file or directory (os error 2)
MacBookPro uv % 

Would the desired result would be something like the following?

My guess is that this occurs in cases where people want to run a specific python version with uv, but is not available in their current environment.

# If command starts with string `python` 
error: Failed to spawn: `python3.9`
  Caused by:  Command `python3.9` not found. Check the list of available python versions with `uv python list`.
# For other not found commands
error: Failed to spawn: `some_command`
  Caused by:  Command `some_command` not found.

Does this sound okay? If so, I can create a PR for this update.

[zanieb]

Yeah you could take a swing at it!

I don't think we can just do startswith, that could match something like python-foo; it'd have to be python<version> specifically.

I think we'd want to say something like..

python3.12 is not available in the current environment which uses Python 3.11. Did you mean uv run -p 3.12 python or uvx [email protected]?

We may need to add more context based on whether or not run is happening in a project or not (I think the split is here). For example

python3.12 is not available in the project environment which uses Python 3.11. Did you mean to change the environment to Python 3.12 with uv run -p 3.12 python?

and

python3.12 is not available in the virtual environment which was created with Python 3.11. Did you mean to search for a Python 3.12 environment with uv run -p 3.12 python?

We could also have a note about uvx, like..

or did you mean to create a temporary Python 3.12 environment with uvx [email protected]?

[JWLee89]

@zanieb Thank you for the clarification! 🙇
This is my first time using / working with UV so my background knowledge will be quite shallow.

I don't think we can just do startswith, that could match something like python-foo; it'd have to be python specifically.

Good point. Would the following suggestion be okay?

// Matches strings like: 
// "python3", "python3.9", "python3.10", "python4", etc.
// But NOT "python-foo", "python39", "python3abc", "python3.12b3".
// "python3.13.3" is also invalid because we cannot specify patch version when attempting to invoke python via the cli
// However, we might want to be able to specify patch version because 
// `uv python pin` also works with patch versions e.g. `uv python pin 3.8.13`
fn is_python_executable_name(name: &str) -> bool {
    // If this pattern is re-used or there is a common location for regex patterns, we can move this
    let pattern = r"^(?i)python[0-9](\.[0-9]+)?$";
    let re = Regex::new(pattern).expect("Invalid regex");
    re.is_match(name)
}

If we want to make this even more robust and see if we get a response from the shell, we can also incorporate the following check:

// Check whether we get some return such as `Python 3.12.5`
let output = Command::new(candidate)
        .arg("--version")
        .output()
        .map_err(|e| anyhow!("Failed to spawn command `{}`: {}", candidate.display(), e))?;
// Todo, check whether output yields something like `Python x.x.x`

This + combination of the regex check is likely the most reliable method but might be overkill. For now, I will prioritize on safety first.

python3.12 is not available in the current environment which uses Python 3.11. Did you mean uv run -p 3.12 python or uvx [email protected]?

My guess is that the python versions mentioned above are derived from:

python3.12 -> from user prompt. E.g. cargo run -- run python3.9 will output python3.9

We need to check whether python<version> is an available python environment instead of solely relying on startswith, since that will not catch cases such as python-foo as you mentioned.

Python 3.11 -> from interpreter: E.g. using base_interpreter.python_version() (whatever version we are pinned to currently)

My current implementation outputs the following:

Regarding the environment, I am assuming that we will need a different message depending on the following two cases:

1. In a project

Generate error message using definitions above.

2. Not in a project - split defined:

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

   Line 779 in 40dce4e

   debug!("No project found; searching for Python interpreter");

Generate the following message, using the python version definitions

{user_input_python_version} is not available in the virtual environment which was created with {interpreter_python_version). Did you mean to search for a {user_input_python_version} environment with uv run -p {user_input_python_version} python?

If so, I will work on this during my spare time and submit a PR.
(it might take a while, since I need to familiarize myself with the codebase and during the week, I need to focus on my day job).

Does this sound okay?

Thank you for your patience! 🙇

[zanieb]

Sorry I have limited time to reply here so I might be a bit brief.

Regarding is_python_executable_name — you should be able to use some existing code. Perhaps you can abstract something from inside

uv/crates/uv-python/src/discovery.rs

Line 543 in 3a53ec3

fn find_all_minor(

and

uv/crates/uv-python/src/implementation.rs

Line 36 in 2966471

pub(crate) fn iter_all() -> impl Iterator<Item = Self> {

If we want to make this even more robust and see if we get a response from the shell, we can also incorporate the following check:

I don't think you need to do this.

Otherwise I think what you've written makes sense!

[JWLee89]

@zanieb Thanks for the clarification.
I will take a stab at the PR during the weekend when I have more time.

Is there a recommended location inside of uv to write unit tests?

The reason why I am asking is because I saw the following folder: https://github.com/astral-sh/uv/tree/main/crates/uv/tests/it,
which I assume is supposed ton contain only integration tests here and not unit tests.

Thank you once again!

[nkitsaini]

Is there a recommended location inside of uv to write unit tests?

Most of the unit tests live in the same file as the code. Example:

uv/crates/uv-distribution-filename/src/wheel.rs

Lines 385 to 413 in 4f70d14

	mod tests {
	use super::*;
	#[test]
	fn err_not_whl_extension() {
	let err = WheelFilename::from_str("foo.rs").unwrap_err();
	insta::assert_snapshot!(err, @r###"The wheel filename "foo.rs" is invalid: Must end with .whl"###);
	}
	#[test]
	fn err_1_part_empty() {
	let err = WheelFilename::from_str(".whl").unwrap_err();
	insta::assert_snapshot!(err, @r###"The wheel filename ".whl" is invalid: Must have a version"###);
	}
	#[test]
	fn err_1_part_no_version() {
	let err = WheelFilename::from_str("foo.whl").unwrap_err();
	insta::assert_snapshot!(err, @r###"The wheel filename "foo.whl" is invalid: Must have a version"###);
	}
	#[test]
	fn err_2_part_no_pythontag() {
	let err = WheelFilename::from_str("foo-1.2.3.whl").unwrap_err();
	insta::assert_snapshot!(err, @r###"The wheel filename "foo-1.2.3.whl" is invalid: Must have a Python tag"###);
	}
	#[test]
	fn err_3_part_no_abitag() {

[JWLee89]

@nkitsaini Ahh I see. If I don't find unit tests within a specific file, I guess I can just add the mod tests block and write the tests there.

Thank you for the clarification! 👍

[JWLee89]

@zanieb @nkitsaini Hi :)

I just created a preliminary PR here: #12201
from where we can start discussion / finalize specs for updates and make the appropriate modifications.

Just wanted to give you both a heads up.

I might not be able to follow up quickly during the week, but I will do my best to follow up during the weekend.

Thank you for the helpful responses in this thread!