mirror of
https://git.datalinker.icu/comfyanonymous/ComfyUI
synced 2026-09-06 19:17:09 +08:00
docs: update UV Migration Guide with new installation options and setup instructions
This commit is contained in:
Mister K
parent
4d1fa555fa
commit
5c08b23fa3
153
UV_MIGRATION.md
153
UV_MIGRATION.md
@ -1,83 +1,132 @@
|
||||
# ComfyUI Migration to UV Package Manager
|
||||
# UV Migration Guide for ComfyUI
|
||||
|
||||
This document provides instructions for migrating to UV-based package management for ComfyUI.
|
||||
|
||||
## What is UV?
|
||||
|
||||
[UV](https://github.com/astral-sh/uv) is a modern Python package installer and resolver written in Rust. It serves as a drop-in replacement for pip with significant performance improvements:
|
||||
[UV](https://github.com/astral-sh/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.
|
||||
|
||||
- **Speed**: UV installs packages 10-100x faster than pip
|
||||
- **Reliability**: Better dependency resolution to avoid conflicts
|
||||
- **Compatibility**: Works with existing requirements.txt files
|
||||
- **Modern**: Built with Rust for performance and safety
|
||||
## Installation Options
|
||||
|
||||
## Why Migrate from pip to UV?
|
||||
### Option 1: Install ComfyUI as a UV Package (Recommended)
|
||||
|
||||
- Faster installation of dependencies
|
||||
- Improved virtual environment management
|
||||
- Better handling of dependency conflicts
|
||||
- Consistent installation experience across platforms
|
||||
- Compatibility with existing pip workflows
|
||||
|
||||
## Installation
|
||||
|
||||
Install UV:
|
||||
This new approach treats ComfyUI as a proper Python package that can be installed using UV:
|
||||
|
||||
```bash
|
||||
# Install UV
|
||||
# Install UV if you don't have it already
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
|
||||
# Add to PATH (bash/zsh)
|
||||
source $HOME/.local/bin/env
|
||||
# Create virtual environment
|
||||
uv venv .venv
|
||||
source .venv/bin/activate # On Linux/macOS
|
||||
# OR
|
||||
.venv\Scripts\activate # On Windows
|
||||
|
||||
# Or for fish shell
|
||||
# source $HOME/.local/bin/env.fish
|
||||
# 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]"
|
||||
```
|
||||
|
||||
## Using UV with ComfyUI
|
||||
|
||||
### Basic Usage
|
||||
After installation, you can run ComfyUI simply by typing:
|
||||
|
||||
```bash
|
||||
# Create a virtual environment
|
||||
uv venv
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
# .venv\Scripts\activate # On Windows
|
||||
# OR
|
||||
.venv\Scripts\activate # On Windows
|
||||
|
||||
# Install dependencies
|
||||
uv pip install -r requirements.txt
|
||||
|
||||
# Install advanced dependencies (if needed)
|
||||
uv pip install -r requirements_advanced.txt
|
||||
```
|
||||
|
||||
### UV Native Commands
|
||||
## Available Extras
|
||||
|
||||
Instead of using the pip-compatible interface, you can use UV's native commands:
|
||||
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:
|
||||
```bash
|
||||
uv pip install "comfyui[gpu,advanced,dev]"
|
||||
```
|
||||
|
||||
## Command-Line Options
|
||||
|
||||
When installed as a package, you can use the `comfyui` command with various options:
|
||||
|
||||
```bash
|
||||
# Install packages
|
||||
uv add packagename
|
||||
|
||||
# Install dev dependencies
|
||||
uv add --dev pytest black
|
||||
|
||||
# View dependency tree
|
||||
uv tree
|
||||
|
||||
# Update dependencies
|
||||
uv sync
|
||||
comfyui --host 0.0.0.0 --port 8188 --auto-launch
|
||||
```
|
||||
|
||||
## Migration Tips
|
||||
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
|
||||
|
||||
1. UV is designed to be a drop-in replacement for pip, so most commands work similarly
|
||||
2. Existing requirements.txt files are fully compatible
|
||||
3. For best results, start with a fresh virtual environment
|
||||
4. UV includes built-in lockfile support for reproducible environments
|
||||
## 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
|
||||
|
||||
If you encounter issues:
|
||||
- **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.
|
||||
|
||||
- Ensure you have the latest version of UV: `uv self update`
|
||||
- Try running with verbose output: `uv -vvv pip install -r requirements.txt`
|
||||
- Check the [UV documentation](https://github.com/astral-sh/uv) for known issues
|
||||
For additional help, please visit our [Discord](https://comfy.org/discord) or [GitHub repository](https://github.com/comfyanonymous/ComfyUI).
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user