Skip to content

The behavior of the %uv line magic is not intuitive #15240

@Gravifer

Description

@Gravifer

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

%colors nocolor
%uv??
%colors lightbg
Source:
    @line_magic
    def uv(self, line):
        """Run the uv package manager within the current kernel.

        Usage:
          %uv pip install [pkgs]
        """
        python = sys.executable
        if sys.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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions