Summary

Inside a project, running uv run --with jupyter jupyter lab correctly adds _uv_ephemeral_overlay.pth to the ephemeral environment created for jupyter. However, the _uv_ephemeral_overlay.pth file is never cleaned up, so subsequent uses of that cached ephemeral environment will see it too. In most cases this doesn't matter because it will be overwritten, but uv tool run (uvx) will not overwrite it. In this example, running uvx jupyter lab elsewhere on the system matches the same cached environment and therefore incorrectly includes the original project virtual env in sys.path.

Example

uv init my-project
cd my-project
uv run --with jupyter jupyter lab

# Print sys.path inside a Jupyter cell. See that the current project venv is correctly on the path
# Ctrl-C to quit Jupyter

cd /some-other-folder
uvx jupyter lab

# Print sys.path inside a Jupyter cell. See that my-project/.venv is incorrectly on the path, 
# despite the fact that this should be an entirely isolated environment

uv cache clean
uvx jupyter lab

# Print sys.path inside a Jupyter cell. See that my-project/.venv is gone, because the
# left-over _uv_ephemeral_overlay.pth is no longer in the ephemeral environment.

This happens with both uvx and uv tool run, and appears to be because uv run --with x and uv tool run x match the same cached ephemeral environment, even though uv run leaves behind the .pth file.

N.B. This problem is not caused by the PR that added _uv_ephemeral_overlay.pth - the previous implemention using sitecustomize.py had the same problem.

I think the solution may be as simple as cleaning up _uv_ephemeral_overlay.pth before using the chosen environment for uv tool run, but I'm unfamiliar with Rust in general and this codebase in particular, so would be hesitant to open a PR directly.

Platform

macOS 14 arm64 and Windows 11 x86_64

Version

uv 0.5.25 (9c07c3f 2025-01-28)

Python version

Python 3.12.0