You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Behavior of the %uv line magic is not intuitive #15240
Since v8.29, there has been a line magic %uv for uv, similar for how %pip works for pip;
as of now, the line magic is implemented as
%colorsnocolor
%uv??
%colorslightbg
Source:
@line_magicdefuv(self, line):
"""Run the uv package manager within the current kernel. Usage: %uv pip install [pkgs] """python=sys.executableifsys.platform=="win32":
python='"'+python+'"'else:
python=shlex.quote(python)
self.shell.system(" ".join([python, "-m", "uv", line]))
print("Note: you may need to restart the kernel to use updated packages.")
File: /workspaces/project/.venv/lib/python3.13/site-packages/IPython/core/magics/packaging.py
Which, for a kernel running in a uv managed venv, does not work unless the shim wheel is added via uv add uv or uv pip install uv.
However, uv's working model with virtual environments is quite different from pip's;
while pip normally needs itself to be put as a site package in the environment (and the system wide instance knows nothing of it), uv us aware of the virtual environment from the outside. Adding the uv wheel as a dependency actually just put a copy of the uv binary together with a init.py to make it a module, introducing a nerving circular dependency.
While I think the implementation is still reasonable, and users can be left to use this magic if they like to, the docstring in its current state does not reflect this subtlety, and may leave people the impression that eiher uv works exactly as pip, or that the line magics handles the two tools with their respective quirks.
See also astral-sh/uv#6329 for some existing conversation regardiing the interaction of uv and Jupyter.
I can work on clarifying the %uv documentation. My understanding is that the current implementation (python -m uv) is intentional, and the issue is primarily that the docstring does not explain that %uv requires the uv Python module to be available in the current environment, unlike typical uv binary usage.
If that interpretation is correct, I'd be happy to open a small PR updating the docstring (and any related documentation).
Activity
[-]The behavior of the `%uv` line magic is not intuitive[/-][+]Behavior of the `%uv` line magic is not intuitive[/+]UTSAV-2024 commentedon Jun 13, 2026
I can work on clarifying the
%uvdocumentation. My understanding is that the current implementation (python -m uv) is intentional, and the issue is primarily that the docstring does not explain that%uvrequires theuvPython module to be available in the current environment, unlike typicaluvbinary usage.If that interpretation is correct, I'd be happy to open a small PR updating the docstring (and any related documentation).
Gravifer commentedon Jul 26, 2026
I also think that even just recommending
!uvover%uvwould suffice.