Packaging

packaging

Centralized UV package management.

All Python package installations go through :func:uv_install. No pip fallback — uv is required (the bootstrap downloads it).

Replaces all raw python -m pip install calls across the codebase.

UvNotFoundError

Bases: RuntimeError

Raised when uv is not available on the system.

uv_install(python_exe, packages=None, *, index_url=None, requirements=None, upgrade=False, no_build_isolation=False, no_deps=False, editable=None, ignore_errors=False, timeout=600, log=None)

Install Python packages via uv pip install.

Builds the full uv pip install command and delegates to :func:~src.utils.commands.run_and_log.

Parameters:

Name	Type	Description	Default
python_exe	Path	Path to the target venv Python executable. Passed as --python so the venv does not need to be activated.	required
packages	list[str] | None	Package specifiers to install (e.g. ["torch==2.10"]).	None
index_url	str | None	PyPI index URL override (--index-url).	None
requirements	Path | None	Path to a requirements.txt file (-r).	None
upgrade	bool	If True, add --upgrade.	False
no_build_isolation	bool	If True, add --no-build-isolation.	False
no_deps	bool	If True, add --no-deps.	False
editable	Path | None	Path to install in editable mode (-e).	None
ignore_errors	bool	Forwarded to :func:run_and_log.	False
timeout	int	Command timeout in seconds.	600

Returns:

Type	Description
CompletedProcess[str]	The completed process result.

Raises:

Type	Description
UvNotFoundError	If uv is not available.
CommandError	If the command fails and ignore_errors is False.

Source code in src/utils/packaging.py

def uv_install(
    python_exe: Path,
    packages: list[str] | None = None,
    *,
    index_url: str | None = None,
    requirements: Path | None = None,
    upgrade: bool = False,
    no_build_isolation: bool = False,
    no_deps: bool = False,
    editable: Path | None = None,
    ignore_errors: bool = False,
    timeout: int = 600,
    log: InstallerLogger | None = None,
) -> subprocess.CompletedProcess[str]:
    """Install Python packages via ``uv pip install``.

    Builds the full ``uv pip install`` command and delegates to
    :func:`~src.utils.commands.run_and_log`.

    Args:
        python_exe: Path to the target venv Python executable.
            Passed as ``--python`` so the venv does not need to be
            activated.
        packages: Package specifiers to install (e.g. ``["torch==2.10"]``).
        index_url: PyPI index URL override (``--index-url``).
        requirements: Path to a ``requirements.txt`` file (``-r``).
        upgrade: If ``True``, add ``--upgrade``.
        no_build_isolation: If ``True``, add ``--no-build-isolation``.
        no_deps: If ``True``, add ``--no-deps``.
        editable: Path to install in editable mode (``-e``).
        ignore_errors: Forwarded to :func:`run_and_log`.
        timeout: Command timeout in seconds.

    Returns:
        The completed process result.

    Raises:
        UvNotFoundError: If ``uv`` is not available.
        CommandError: If the command fails and *ignore_errors* is False.
    """
    uv_path = _ensure_uv()
    if log is None:
        log = get_logger()

    args: list[str] = ["pip", "install", "--python", str(python_exe)]

    if upgrade:
        args.append("--upgrade")

    if index_url:
        args.extend(["--index-url", index_url])

    if no_build_isolation:
        args.append("--no-build-isolation")

    if no_deps:
        args.append("--no-deps")

    if requirements:
        args.extend(["-r", str(requirements)])

    if editable:
        args.extend(["-e", str(editable)])

    if packages:
        args.extend(packages)

    log.info(f"uv {' '.join(args)}")

    return run_and_log(
        uv_path,
        args,
        ignore_errors=ignore_errors,
        timeout=timeout,
    )