ComfyUI/UV_MIGRATION.md

UV Migration Guide for ComfyUI

This document provides instructions for migrating to UV-based package management for ComfyUI.

What is UV?

UV is a modern, ultra-fast package manager for Python. It's up to 10-100x faster than pip and provides better dependency resolution, lockfile support, and caching. UV is designed to be a drop-in replacement for pip, but with better performance and reliability.

Installation Options

Option 1: Install ComfyUI as a UV Package (Recommended)

This new approach treats ComfyUI as a proper Python package that can be installed using UV:

# Install UV if you don't have it already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv .venv
source .venv/bin/activate  # On Linux/macOS
# OR
.venv\Scripts\activate     # On Windows

# Install ComfyUI with all optional dependencies
uv pip install "comfyui[gpu,advanced]"

# Or install from a specific version:
uv pip install "comfyui==0.3.30[gpu,advanced]"

After installation, you can run ComfyUI simply by typing:

comfyui

Option 2: Use the Automated Setup Script

If you have the ComfyUI source code, you can use our new setup script to handle everything:

# Clone the repository
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI

# Run the setup script
python uv_setup.py --gpu --advanced

Option 3: Traditional Approach (Use UV as pip replacement)

If you prefer the traditional approach but want to use UV:

# Clone the repository
git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI

# Install UV if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv .venv
source .venv/bin/activate  # On Linux/macOS
# OR
.venv\Scripts\activate     # On Windows

# Install dependencies
uv pip install -r requirements.txt

Available Extras

When installing ComfyUI as a package, you can specify extras to include additional dependencies:

• gpu: NVIDIA CUDA libraries for GPU acceleration
• advanced: Additional dependencies for advanced features
• dev: Development dependencies for contributing to ComfyUI

Example:

uv pip install "comfyui[gpu,advanced,dev]"

Command-Line Options

When installed as a package, you can use the comfyui command with various options:

comfyui --host 0.0.0.0 --port 8188 --auto-launch

Common options:

• --host: The IP address to listen on (default: 127.0.0.1)
• --port: The port to listen on (default: 8188)
• --auto-launch: Automatically open ComfyUI in your default browser
• --cuda-device: Specify which CUDA device to use
• --output-directory: Override the default output directory
• --input-directory: Override the default input directory
• --verbose: Enable verbose logging

Migration Command Reference

Below is a quick reference for migrating from pip commands to UV:

pip command	UV command	Description
pip install -r requirements.txt	uv pip install -r requirements.txt	Install from requirements file
pip install package	uv pip install package or uv add package	Install a package
pip install -e .	uv pip install -e .	Install current directory in development mode
pip freeze > requirements.txt	uv pip freeze > requirements.txt	Create requirements file from installed packages

Benefits of UV Package Approach

Installing ComfyUI as a UV package offers several advantages:

1. Simplified Installation: One command to install everything
2. Dependency Management: Faster resolution and better handling of complex dependencies
3. Reproducible Environments: Lock files ensure consistent environments across systems
4. Command-Line Interface: Run ComfyUI from anywhere using the comfyui command
5. Optional Dependencies: Install only what you need via extras
6. Package Updates: Easily update to new versions with uv pip install -U comfyui
7. Development Mode: Better integration with development workflows

Troubleshooting

• Missing packages? Try uv pip install --upgrade -r requirements.txt to reinstall all dependencies.
• Package conflicts? UV has improved dependency resolution, but if issues persist, try uv pip install package --force-reinstall.
• Need to start fresh? Run python clean_venv.py to remove your virtual environment and start over.

For additional help, please visit our Discord or GitHub repository.