Ephemeral environments lacking scripts entry points

[fvbrandt]

Summary

Short summary

Ephemeral environments created via --with do not contain the "scripts" entry points (Windows: scripts/<script>.exe, Linux: bin/<script>) of their base venv. Thus, if one launches such an entry point from an ephemeral venv, one ends up running the interpreter from the base venv which lacks the packages installed by --with.

I already asked about this in discord and @zanieb replied it might be worth opening an issue because it might be a bug.
If it is not a bug, then at least it might be worth a warning in the documentation of the --with parameter.

Minimal example

Windows cmd commands

uv init uvEphemeralScriptsExample
cd uvEphemeralScriptsExample
uv add pytest
# (Now we have an entry point we want to use: .venv/scripts/pytest.exe)
mkdir tests
# Add a test case that depends on another package, e.g. "pyyaml". We will install that package via --with
(echo def test_pyyaml^(^):& echo     import yaml)> tests\test_pyyaml.py
uv run --with pyyaml python -c "import subprocess;subprocess.run(['pytest'], text=True)"

Work arounds / why is this bad?

In my particular use case the script I needed was pytest and a work around was to call [sys.executable, "-m", "pytest"].

But the pytest docs have an explicit warning that this triggers slightly different behavior: https://docs.pytest.org/en/7.1.x/explanation/pythonpath.html#invoking-pytest-versus-python-m-pytest

Also, other python packages might define more complicated entry points and trying to circumvent the entry-points to directly call the underlying API seems like bad practice.

Platform

Windows

Version

uv 0.7.2 (481d05d 2025-04-30)

Python version

tested on 3.9 and 3.13

[hynek]

Ooof thanks for opening this issue, because this is a really nasty one and I would be still debugging otherwise!

The fact that uv run --with pdbpp python -c 'import pdbpp' works and uv run --with pdbpp pytest claims pdbpp isn't installed is really confusing. 😅

[zanieb]

@hynek just to be clear, the latter claims that pytest isn't installed, yes?

[hynek]

@hynek just to be clear, the latter claims that pytest isn't installed, yes?

No, much worse. :)

It falls back to the pytest from the main venv which means the --with is meaningless.

[zanieb]

I see, that makes more sense.

The fix here is presumably to copy over all the entry points from the parent environment with a re-written shebang, unless an entry point already exists in the ephemeral layer.

[hynek]

BTW, I would argue that the correct behavior here would be to only look at the venv's bin directory like tox – or at least warning if the command is coming from somewhere else. It's really hard to debug once a transparent fallback happens.

[zanieb]

That'd be really breaking and confusing, e.g., uv run bash -c "..." would warn?

It might be reasonable to warn if a command comes from another Python environment, but not just if it's from outside the virtual environment.

[hynek]

It might be reasonable to warn if a command comes from another Python environment, but not just if it's from outside the virtual environment.

ah yes, that!

especially if it's the main one. that was really super confusing to debug. 😅