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.

find_uv(install_path=None, python_exe=None)

Find the uv executable.

Checks the local scripts/uv/ directory first (where the bootstrap installs it), then falls back to the system PATH.

When install_path is not provided but python_exe is, the install root is derived from the venv Python path::

{install_path}/scripts/venv/Scripts/python.exe  (Windows)
{install_path}/scripts/venv/bin/python           (Linux)

Parameters:

Name	Type	Description	Default
install_path	Path | None	Root install directory (e.g. ~/ComfyUI). If provided, checks install_path/scripts/uv/uv[.exe].	None
python_exe	Path | None	Path to the venv Python executable. Used to auto-detect install_path when not explicitly given.	None

Returns:

Type	Description
str | None	Absolute path to uv, or None if not found.

Source code in src/utils/packaging.py

def find_uv(
    install_path: Path | None = None,
    python_exe: Path | None = None,
) -> str | None:
    """Find the ``uv`` executable.

    Checks the local ``scripts/uv/`` directory first (where the
    bootstrap installs it), then falls back to the system PATH.

    When *install_path* is not provided but *python_exe* is, the
    install root is derived from the venv Python path::

        {install_path}/scripts/venv/Scripts/python.exe  (Windows)
        {install_path}/scripts/venv/bin/python           (Linux)

    Args:
        install_path: Root install directory (e.g. ``~/ComfyUI``).
            If provided, checks ``install_path/scripts/uv/uv[.exe]``.
        python_exe: Path to the venv Python executable. Used to
            auto-detect *install_path* when not explicitly given.

    Returns:
        Absolute path to ``uv``, or ``None`` if not found.
    """
    import shutil
    import sys

    uv_name = "uv.exe" if sys.platform == "win32" else "uv"

    # 1. Check explicit install path
    if install_path is not None:
        local_uv = install_path / "scripts" / "uv" / uv_name
        if local_uv.is_file():
            return str(local_uv)

    # 2. Auto-detect from python_exe path
    #    python_exe is {install}/scripts/venv/Scripts/python.exe (win)
    #    or             {install}/scripts/venv/bin/python         (linux)
    if python_exe is not None:
        from pathlib import Path

        exe = Path(python_exe).resolve()
        # Walk up to find a parent containing scripts/uv/
        for candidate in exe.parents:
            local_uv = candidate / "scripts" / "uv" / uv_name
            if local_uv.is_file():
                return str(local_uv)

    # 3. Check next to the current running Python executable
    # (This is where pip installs `uv` if the user installed the wheel globally/in a venv)
    from pathlib import Path

    pip_uv = Path(sys.executable).parent / uv_name
    if pip_uv.is_file():
        return str(pip_uv)

    # 4. Fall back to system PATH
    path = shutil.which("uv")
    return path

uv_install(python_exe, packages=None, *, index_url=None, requirements=None, upgrade=False, no_build_isolation=False, no_deps=False, no_cache=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
no_cache	bool	If True, add --no-cache.	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,
    no_cache: 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``.
        no_cache: If ``True``, add ``--no-cache``.
        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(python_exe=python_exe)
    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 no_cache:
        args.append("--no-cache")

    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,
    )