From 6e58131add70a95f589a4d9a69c6ef1d13cb2908 Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:26:01 +0800 Subject: [PATCH 01/11] Add UV package manager support and installation instructions --- .github/workflows/uv-build.yml | 26 ++++++ CONTRIBUTING.md | 38 ++++++++ README.md | 29 ++++++ UV_MIGRATION.md | 83 +++++++++++++++++ convert_requirements_to_pyproject.py | 75 +++++++++++++++ install_with_uv.py | 132 +++++++++++++++++++++++++++ pyproject.toml | 13 +++ 7 files changed, 396 insertions(+) create mode 100644 .github/workflows/uv-build.yml create mode 100644 UV_MIGRATION.md create mode 100644 convert_requirements_to_pyproject.py create mode 100644 install_with_uv.py diff --git a/.github/workflows/uv-build.yml b/.github/workflows/uv-build.yml new file mode 100644 index 000000000..48e8a9af6 --- /dev/null +++ b/.github/workflows/uv-build.yml @@ -0,0 +1,26 @@ +name: Build and Test + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + - name: Install uv + run: | + curl -LsSf https://astral.sh/uv/install.sh | sh + echo "$HOME/.local/bin" >> $GITHUB_PATH + - name: Install dependencies + run: | + uv pip install -r requirements.txt + uv pip install -r requirements_advanced.txt + # Additional steps... diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 048f127e7..e55e09a6c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,6 +35,44 @@ If you cannot find an existing issue that describes your bug or feature, create * Please refer to the article on [creating pull requests](https://github.com/comfyanonymous/ComfyUI/wiki/How-to-Contribute-Code) and contributing to this project. +## Development Environment Setup + +### Setting Up with UV (Recommended) + +*Added 2025-05-02 by kairin* + +We recommend using [UV](https://github.com/astral-sh/uv) for faster, more reliable package management: + +1. **Install UV**: + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + source $HOME/.local/bin/env # For bash/zsh + ``` + +2. **Set up development environment**: + ```bash + git clone https://github.com/comfyanonymous/ComfyUI.git + cd ComfyUI + + # Create virtual environment + uv venv + source .venv/bin/activate # Linux/macOS + # or + .venv\Scripts\activate # Windows + + # Install dependencies + uv pip install -r requirements.txt + + # Install development dependencies + uv add --dev pytest black isort + ``` + +3. **Install in development mode**: + ```bash + uv pip install -e . + ``` + +### Working with Dependencies ## Thank You diff --git a/README.md b/README.md index 0f39cfce2..92e014a69 100644 --- a/README.md +++ b/README.md @@ -192,6 +192,35 @@ Put your SD checkpoints (the huge ckpt/safetensors files) in: models/checkpoints Put your VAE in: models/vae +## Installation Options + +### Option 1: Install with UV (Recommended) + +*Added 2025-05-02* + +[UV](https://github.com/astral-sh/uv) is a faster, more reliable Python package installer that we now recommend for ComfyUI. + +1. **Install UV**: + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + source $HOME/.local/bin/env # For bash/zsh + ``` + +2. **Install ComfyUI dependencies**: + ```bash + # Create and activate virtual environment + uv venv + source .venv/bin/activate # Linux/macOS + # or + .venv\Scripts\activate # Windows + + # Install dependencies + uv pip install -r requirements.txt + ``` + +For detailed instructions on using UV with ComfyUI, see our [UV Migration Guide](UV_MIGRATION.md). + +### Option 2: Install with pip (Traditional) ### AMD GPUs (Linux only) AMD users can install rocm and pytorch with pip if you don't have it already installed, this is the command to install the stable version: diff --git a/UV_MIGRATION.md b/UV_MIGRATION.md new file mode 100644 index 000000000..cbf45cf23 --- /dev/null +++ b/UV_MIGRATION.md @@ -0,0 +1,83 @@ +# ComfyUI Migration to UV Package Manager + +## 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: + +- **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 + +## Why Migrate from pip to UV? + +- 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: + +```bash +# Install UV +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Add to PATH (bash/zsh) +source $HOME/.local/bin/env + +# Or for fish shell +# source $HOME/.local/bin/env.fish +``` + +## Using UV with ComfyUI + +### Basic Usage + +```bash +# Create a virtual environment +uv venv +source .venv/bin/activate # On Linux/macOS +# .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 + +Instead of using the pip-compatible interface, you can use UV's native commands: + +```bash +# Install packages +uv add packagename + +# Install dev dependencies +uv add --dev pytest black + +# View dependency tree +uv tree + +# Update dependencies +uv sync +``` + +## Migration Tips + +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 + +## Troubleshooting + +If you encounter issues: + +- 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 diff --git a/convert_requirements_to_pyproject.py b/convert_requirements_to_pyproject.py new file mode 100644 index 000000000..74219ea0a --- /dev/null +++ b/convert_requirements_to_pyproject.py @@ -0,0 +1,75 @@ +#!/usr/bin/env python3 +""" +Convert requirements.txt to pyproject.toml dependencies +""" + +import re +import toml +from pathlib import Path + +def parse_requirements(file_path): + """Parse requirements file into a list of packages.""" + requirements = [] + + with open(file_path, 'r') as f: + for line in f: + line = line.strip() + if line and not line.startswith('#') and not line.startswith('-r'): + requirements.append(line) + + return requirements + +def main(): + project_root = Path(__file__).parent + pyproject_path = project_root / "pyproject.toml" + + # Parse requirements + requirements = parse_requirements(project_root / "requirements.txt") + + try: + advanced_requirements = parse_requirements(project_root / "requirements_advanced.txt") + except FileNotFoundError: + advanced_requirements = [] + + # Load existing pyproject.toml if it exists + if pyproject_path.exists(): + with open(pyproject_path, 'r') as f: + pyproject_data = toml.load(f) + else: + # Create basic structure + pyproject_data = { + "build-system": { + "requires": ["setuptools>=42", "wheel"], + "build-backend": "setuptools.build_meta" + }, + "project": { + "name": "ComfyUI", + "version": "0.1.0", + "description": "The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface.", + "readme": "README.md", + "requires-python": ">=3.8", + "dependencies": requirements + } + } + + # Update dependencies + if "project" not in pyproject_data: + pyproject_data["project"] = {} + + pyproject_data["project"]["dependencies"] = requirements + + # Add optional dependencies + if advanced_requirements: + if "optional-dependencies" not in pyproject_data["project"]: + pyproject_data["project"]["optional-dependencies"] = {} + + pyproject_data["project"]["optional-dependencies"]["advanced"] = advanced_requirements + + # Save updated pyproject.toml + with open(pyproject_path, 'w') as f: + toml.dump(pyproject_data, f) + + print(f"Updated {pyproject_path} with dependencies from requirements files") + +if __name__ == "__main__": + main() diff --git a/install_with_uv.py b/install_with_uv.py new file mode 100644 index 000000000..c7ed79864 --- /dev/null +++ b/install_with_uv.py @@ -0,0 +1,132 @@ +#!/usr/bin/env python3 +""" +ComfyUI Installation Script using UV +""" + +import os +import platform +import subprocess +import sys +import shutil +from pathlib import Path +import argparse +from datetime import datetime + +def check_python_version(): + """Check if Python version is supported.""" + if sys.version_info < (3, 8): + print("Python 3.8 or higher is required.") + sys.exit(1) + +def install_uv(): + """Install UV if not already installed.""" + if shutil.which("uv") is None: + print("Installing UV package manager...") + try: + if platform.system() == "Windows": + # For Windows, download and run the installer + subprocess.check_call( + ["powershell", "-Command", + "Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -OutFile install.ps1; ./install.ps1"], + stdout=sys.stdout, stderr=sys.stderr + ) + else: + # For macOS and Linux + subprocess.check_call( + ["bash", "-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"], + stdout=sys.stdout, stderr=sys.stderr + ) + print("UV installed successfully.") + except subprocess.CalledProcessError: + print("Failed to install UV. Please install it manually from https://github.com/astral-sh/uv") + sys.exit(1) + else: + print("UV is already installed.") + +def create_venv(): + """Create a virtual environment using UV.""" + print("Creating virtual environment...") + try: + subprocess.check_call( + ["uv", "venv", ".venv"], + stdout=sys.stdout, stderr=sys.stderr + ) + print("Virtual environment created successfully.") + except subprocess.CalledProcessError: + print("Failed to create virtual environment.") + sys.exit(1) + +def activate_venv(): + """Return the activation command for the virtual environment.""" + if platform.system() == "Windows": + return str(Path(".venv/Scripts/activate")) + return f"source {str(Path('.venv/bin/activate'))}" + +def install_requirements(args): + """Install ComfyUI requirements using UV.""" + print("Installing requirements...") + + # Basic requirements + try: + subprocess.check_call( + ["uv", "pip", "install", "-r", "requirements.txt"], + stdout=sys.stdout, stderr=sys.stderr + ) + print("Basic requirements installed successfully.") + except subprocess.CalledProcessError: + print("Failed to install basic requirements.") + sys.exit(1) + + # Advanced requirements if specified + if args.advanced: + try: + if os.path.exists("requirements_advanced.txt"): + subprocess.check_call( + ["uv", "pip", "install", "-r", "requirements_advanced.txt"], + stdout=sys.stdout, stderr=sys.stderr + ) + print("Advanced requirements installed successfully.") + else: + print("Advanced requirements file not found.") + except subprocess.CalledProcessError: + print("Failed to install advanced requirements.") + sys.exit(1) + + # GPU requirements if specified + if args.gpu: + print("Installing PyTorch with CUDA support...") + try: + subprocess.check_call( + ["uv", "pip", "install", "torch", "torchvision", "torchaudio", "--index-url", "https://download.pytorch.org/whl/cu118"], + stdout=sys.stdout, stderr=sys.stderr + ) + print("PyTorch with CUDA installed successfully.") + except subprocess.CalledProcessError: + print("Failed to install PyTorch with CUDA.") + sys.exit(1) + +def main(): + parser = argparse.ArgumentParser(description="Install ComfyUI with UV package manager") + parser.add_argument("--advanced", action="store_true", help="Install advanced requirements") + parser.add_argument("--gpu", action="store_true", help="Install PyTorch with CUDA support") + parser.add_argument("--no-venv", action="store_true", help="Skip virtual environment creation") + args = parser.parse_args() + + print(f"ComfyUI installation with UV started at {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}") + + check_python_version() + install_uv() + + if not args.no_venv: + create_venv() + print(f"To activate the virtual environment, run: {activate_venv()}") + + install_requirements(args) + + print("\nComfyUI installation completed successfully!") + if not args.no_venv: + print(f"Remember to activate the virtual environment with: {activate_venv()}") + print("To start ComfyUI, run: python main.py") + +if __name__ == "__main__": + main() diff --git a/pyproject.toml b/pyproject.toml index a9c028c7e..97420defc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,11 @@ +[build-system] +requires = ["setuptools>=42", "wheel"] +build-backend = "setuptools.build_meta" + [project] name = "ComfyUI" version = "0.3.30" +description = "The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface." readme = "README.md" license = { file = "LICENSE" } requires-python = ">=3.9" @@ -10,6 +15,11 @@ homepage = "https://www.comfy.org/" repository = "https://github.com/comfyanonymous/ComfyUI" documentation = "https://docs.comfy.org/" +[project.optional-dependencies] +advanced = [ + # Include dependencies from requirements_advanced.txt here +] + [tool.ruff] lint.select = [ "N805", # invalid-first-argument-name-for-method @@ -22,3 +32,6 @@ lint.select = [ "F", ] exclude = ["*.ipynb"] + +[tool.uv] +# Add any uv-specific configurations here From 0b49a47b98bdae8d6dbcc59959d6fb44b9553ddb Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:39:23 +0800 Subject: [PATCH 02/11] Add UV environment setup and dependency management scripts --- UV-req-lock.txt | 2 + clean_venv.py | 111 ++++++++++++++++++++++++++++++++++++++ pyproject.toml | 24 ++++++++- requirements.txt | 12 +++++ update_dependencies_uv.py | 104 +++++++++++++++++++++++++++++++++++ uv_setup.sh | 45 ++++++++++++++++ 6 files changed, 297 insertions(+), 1 deletion(-) create mode 100644 UV-req-lock.txt create mode 100755 clean_venv.py create mode 100755 update_dependencies_uv.py create mode 100755 uv_setup.sh diff --git a/UV-req-lock.txt b/UV-req-lock.txt new file mode 100644 index 000000000..8cf3abeb0 --- /dev/null +++ b/UV-req-lock.txt @@ -0,0 +1,2 @@ +pip==24.0 +setuptools==65.5.0 diff --git a/clean_venv.py b/clean_venv.py new file mode 100755 index 000000000..e6e89ab1f --- /dev/null +++ b/clean_venv.py @@ -0,0 +1,111 @@ +#!/usr/bin/env python3 +""" +ComfyUI Virtual Environment Cleanup Script +Created: May 2, 2025 +""" + +import argparse +import os +import shutil +import sys +import platform +from pathlib import Path + +def deactivate_venv(): + """Attempt to deactivate any active virtual environment.""" + if "VIRTUAL_ENV" in os.environ: + print(f"Active virtual environment detected: {os.environ['VIRTUAL_ENV']}") + print("Attempting to deactivate...") + + # This won't actually deactivate within this process since Python can't modify + # its parent environment, but it will provide instructions to the user + print("\nTo properly deactivate your virtual environment, please run:") + if platform.system() == "Windows": + print(" deactivate") + else: + print(" deactivate") + + print("\nAfter deactivating, run this script again.") + return True + return False + +def remove_venv(venv_path, force=False): + """Remove a virtual environment directory if it exists.""" + path = Path(venv_path).expanduser().resolve() + + if not path.exists(): + print(f"Virtual environment not found at: {path}") + return False + + # Safety check - make sure it looks like a venv + is_venv = False + if platform.system() == "Windows": + is_venv = (path / "Scripts" / "python.exe").exists() + else: + is_venv = (path / "bin" / "python").exists() + + if not is_venv and not force: + print(f"Warning: {path} doesn't appear to be a virtual environment.") + print("Use --force to remove it anyway.") + return False + + try: + print(f"Removing virtual environment at: {path}") + shutil.rmtree(path) + print("โœ… Virtual environment removed successfully.") + return True + except Exception as e: + print(f"โŒ Error removing virtual environment: {e}") + if platform.system() == "Windows": + print("\nTry running this script with administrator privileges or closing any") + print("applications that might be using files in the virtual environment.") + else: + print("\nTry running this script with sudo if you have permission issues:") + print(f" sudo rm -rf {path}") + return False + +def main(): + parser = argparse.ArgumentParser(description="Remove ComfyUI virtual environments") + parser.add_argument("--all", action="store_true", help="Remove all known virtual environment locations") + parser.add_argument("--force", action="store_true", help="Force removal even if directory doesn't look like a venv") + parser.add_argument("--venv-path", type=str, help="Path to custom virtual environment to remove") + args = parser.parse_args() + + # Don't proceed if a virtual environment is active + if deactivate_venv(): + return + + # Common venv locations + venv_locations = [ + ".venv", # Default UV venv name + "venv", # Common alternative name + Path.home() / ".venvs" / "comfyui", # User-level venvs + ] + + if args.venv_path: + # Just remove the specified venv + remove_venv(args.venv_path, args.force) + elif args.all: + # Remove all common venv locations + removed_any = False + for venv_loc in venv_locations: + if remove_venv(venv_loc, args.force): + removed_any = True + + if not removed_any: + print("No virtual environments were found in common locations.") + else: + # Default: just remove .venv + if not remove_venv(".venv", args.force): + print("\nTo remove other virtual environment locations, use:") + print(" python clean_venv.py --all") + print(" python clean_venv.py --venv-path /path/to/venv") + + print("\n๐Ÿš€ Ready to create a new UV-based environment!") + print("Run the following commands to set up with UV:") + print(" ./uv_setup.sh") + print(" source .venv/bin/activate # On Linux/macOS") + print(" ./update_dependencies_uv.py --advanced --cuda --lock") + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 97420defc..5361562a0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -34,4 +34,26 @@ lint.select = [ exclude = ["*.ipynb"] [tool.uv] -# Add any uv-specific configurations here +# UV-specific configurations (updated May 2025) +python = "3.11" +system = false +verbosity = 1 +threads = "auto" +no-binary = [] +only-binary = [] + +[tool.uv.dependencies] +# Core dependencies with modern 2025 versions +torch = { version = ">=2.3.0", source = "pytorch" } +torchvision = { version = ">=0.18.0", source = "pytorch" } +numpy = ">=2.0.0" +pillow = ">=10.0.0" +aiohttp = ">=3.9.0" +rich = ">=13.6.0" +tqdm = ">=4.66.0" +transformers = ">=4.38.0" +diffusers = ">=0.25.0" +safetensors = ">=0.4.0" + +[tool.uv.sources] +pytorch = { url = "https://download.pytorch.org/whl/cu121" } diff --git a/requirements.txt b/requirements.txt index 74a4ceb02..bec554918 100644 --- a/requirements.txt +++ b/requirements.txt @@ -17,6 +17,18 @@ Pillow scipy tqdm psutil +opencv-python>=4.8.0 +flash-attn>=2.3.0 +nvidia-cuda-runtime-cu12>=12.0.0 +nvidia-cuda-nvrtc-cu12>=12.0.0 +nvidia-cudnn-cu12>=8.9.0 +nvidia-cublas-cu12>=12.0.0 +nvidia-cufft-cu12>=11.0.0 +nvidia-curand-cu12>=10.3.0 +nvidia-cusolver-cu12>=11.4.0 +nvidia-cusparse-cu12>=12.1.0 +nvidia-nccl-cu12>=2.18.0 +nvidia-nvtx-cu12>=12.0.0 #non essential dependencies: kornia>=0.7.1 diff --git a/update_dependencies_uv.py b/update_dependencies_uv.py new file mode 100755 index 000000000..d488bc66b --- /dev/null +++ b/update_dependencies_uv.py @@ -0,0 +1,104 @@ +#!/usr/bin/env python3 +""" +ComfyUI Dependency Update Script using UV +Created: May 2, 2025 +""" + +import argparse +import os +import platform +import subprocess +import sys + +def check_uv_installed(): + """Check if UV is installed and install if missing.""" + try: + subprocess.run(["uv", "--version"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True) + print("โœ… UV is installed") + return True + except (subprocess.CalledProcessError, FileNotFoundError): + print("โš ๏ธ UV not found. Installing...") + + if platform.system() == "Windows": + subprocess.run( + ["powershell", "-Command", "Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -OutFile install.ps1; ./install.ps1"], + check=True + ) + else: + subprocess.run( + ["bash", "-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"], + check=True + ) + + print("โœ… UV installed successfully") + return True + +def update_dependencies(args): + """Update dependencies using UV.""" + # Ensure we're in a virtual environment + if not os.environ.get("VIRTUAL_ENV") and not args.no_venv_check: + print("โš ๏ธ Not running in a virtual environment. Activate one before updating dependencies.") + print("๐Ÿ’ก Run: uv venv && source .venv/bin/activate (or .venv\\Scripts\\activate on Windows)") + if not args.force: + return False + + print("๐Ÿ“ฆ Updating dependencies using UV...") + + # Update base requirements + subprocess.run(["uv", "pip", "install", "--upgrade", "-r", "requirements.txt"], check=True) + print("โœ… Base dependencies updated") + + # Update advanced requirements if requested + if args.advanced: + subprocess.run(["uv", "pip", "install", "--upgrade", "-r", "requirements_advanced.txt"], check=True) + print("โœ… Advanced dependencies updated") + + # Update PyTorch with CUDA if requested + if args.cuda: + torch_version = "2.4.0" if args.latest else "2.3.0" + cuda_version = "12.1" if args.latest else "11.8" + + print(f"๐Ÿ”„ Installing PyTorch {torch_version} with CUDA {cuda_version}...") + subprocess.run([ + "uv", "pip", "install", "--upgrade", + f"torch=={torch_version}", + f"torchvision>={torch_version}", + f"torchaudio>={torch_version}", + "--index-url", f"https://download.pytorch.org/whl/cu{cuda_version.replace('.', '')}" + ], check=True) + print("โœ… PyTorch updated with CUDA support") + + # Generate lockfile for reproducibility + if args.lock: + print("๐Ÿ”’ Generating lockfile...") + subprocess.run(["uv", "pip", "freeze", ">", "UV-req-lock.txt"], shell=True, check=True) + print("โœ… Lockfile generated: UV-req-lock.txt") + + return True + +def main(): + parser = argparse.ArgumentParser(description="Update ComfyUI dependencies using UV") + parser.add_argument("--advanced", action="store_true", help="Update advanced dependencies") + parser.add_argument("--cuda", action="store_true", help="Update PyTorch with CUDA support") + parser.add_argument("--latest", action="store_true", help="Use latest versions (may be less stable)") + parser.add_argument("--lock", action="store_true", help="Generate lockfile after update") + parser.add_argument("--force", action="store_true", help="Force update even if not in venv") + parser.add_argument("--no-venv-check", action="store_true", help="Skip virtual environment check") + + args = parser.parse_args() + + print("ComfyUI Dependency Update") + print("========================") + + if not check_uv_installed(): + sys.exit(1) + + if update_dependencies(args): + print("\nโœจ Dependencies updated successfully!") + print("\n๐Ÿ’ก To start ComfyUI, run: python main.py") + else: + print("\nโŒ Dependency update failed or was skipped") + sys.exit(1) + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/uv_setup.sh b/uv_setup.sh new file mode 100755 index 000000000..193d45044 --- /dev/null +++ b/uv_setup.sh @@ -0,0 +1,45 @@ +#!/bin/bash +# ComfyUI UV Environment Setup Script +# Created: May 2, 2025 + +# Set UV environment variables for better performance +export UV_CACHE_DIR="${HOME}/.cache/uv" +export UV_SYSTEM_PYTHON=false +export UV_DEFAULT_PYTHON=3.11 +export UV_THREADS=auto +export UV_VERBOSITY=1 + +# Create directory structure if needed +mkdir -p "${UV_CACHE_DIR}" + +echo "UV environment variables set:" +echo " UV_CACHE_DIR: ${UV_CACHE_DIR}" +echo " UV_DEFAULT_PYTHON: ${UV_DEFAULT_PYTHON}" +echo " UV_THREADS: ${UV_THREADS}" + +# Check if UV is installed +if ! command -v uv >/dev/null 2>&1; then + echo "UV not found. Installing..." + curl -LsSf https://astral.sh/uv/install.sh | sh + + # Add to PATH for this session + source $HOME/.local/bin/env +fi + +# Check for ComfyUI virtual environment +if [ ! -d ".venv" ]; then + echo "Creating virtual environment..." + uv venv + echo "Virtual environment created at .venv" +fi + +echo "" +echo "To activate the virtual environment, run:" +echo " source .venv/bin/activate # On Linux/macOS" +echo " .venv\\Scripts\\activate.bat # On Windows" +echo "" +echo "To install/update dependencies:" +echo " ./update_dependencies_uv.py --advanced --cuda --lock" +echo "" +echo "To start ComfyUI:" +echo " python main.py" \ No newline at end of file From 99885f4ae8a8d2c33d137a15ecddb200d4876b94 Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:45:27 +0800 Subject: [PATCH 03/11] Update pyproject.toml with enhanced dependencies and author information; add __init__.py for module initialization --- __init__.py | 7 ++++ pyproject.toml | 112 ++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 100 insertions(+), 19 deletions(-) create mode 100644 __init__.py diff --git a/__init__.py b/__init__.py new file mode 100644 index 000000000..fed5ec43b --- /dev/null +++ b/__init__.py @@ -0,0 +1,7 @@ +""" +ComfyUI - The most powerful and modular diffusion model GUI, API and backend. +""" + +from comfyui_version import __version__ + +__all__ = ["__version__"] \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 5361562a0..c2c9921c2 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,24 +1,87 @@ [build-system] -requires = ["setuptools>=42", "wheel"] +requires = ["setuptools>=61.0.0", "wheel", "uv"] build-backend = "setuptools.build_meta" [project] -name = "ComfyUI" +name = "comfyui" version = "0.3.30" description = "The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface." readme = "README.md" license = { file = "LICENSE" } requires-python = ">=3.9" +authors = [ + { name = "ComfyUI Team", email = "contact@comfy.org" } +] +classifiers = [ + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "License :: OSI Approved :: GNU General Public License v3 (GPLv3)", + "Operating System :: OS Independent", + "Topic :: Scientific/Engineering :: Artificial Intelligence", + "Topic :: Multimedia :: Graphics", +] + +dependencies = [ + "comfyui-frontend-package==1.18.5", + "comfyui-workflow-templates==0.1.3", + "torch>=2.0.0", + "torchsde", + "torchvision", + "torchaudio", + "numpy>=1.25.0", + "einops", + "transformers>=4.28.1", + "tokenizers>=0.13.3", + "sentencepiece", + "safetensors>=0.4.2", + "aiohttp>=3.11.8", + "yarl>=1.18.0", + "pyyaml", + "Pillow", + "scipy", + "tqdm", + "psutil", + "opencv-python>=4.8.0", + "flash-attn>=2.3.0", +] + +[project.optional-dependencies] +gpu = [ + "nvidia-cuda-runtime-cu12>=12.0.0", + "nvidia-cuda-nvrtc-cu12>=12.0.0", + "nvidia-cudnn-cu12>=8.9.0", + "nvidia-cublas-cu12>=12.0.0", + "nvidia-cufft-cu12>=11.0.0", + "nvidia-curand-cu12>=10.3.0", + "nvidia-cusolver-cu12>=11.4.0", + "nvidia-cusparse-cu12>=12.1.0", + "nvidia-nccl-cu12>=2.18.0", + "nvidia-nvtx-cu12>=12.0.0", +] +advanced = [ + "kornia>=0.7.1", + "spandrel", + "soundfile", + "av>=14.2.0", + "pydantic~=2.0", +] +dev = [ + "pytest>=7.0.0", + "black>=23.0.0", + "isort>=5.12.0", + "ruff>=0.0.272", +] [project.urls] homepage = "https://www.comfy.org/" repository = "https://github.com/comfyanonymous/ComfyUI" documentation = "https://docs.comfy.org/" +changelog = "https://github.com/comfyanonymous/ComfyUI/releases" -[project.optional-dependencies] -advanced = [ - # Include dependencies from requirements_advanced.txt here -] +[project.scripts] +comfyui = "comfyui.cli:main" [tool.ruff] lint.select = [ @@ -33,27 +96,38 @@ lint.select = [ ] exclude = ["*.ipynb"] +[tool.setuptools] +packages = ["comfyui"] +package-dir = {"comfyui" = "."} +include-package-data = true + +[tool.setuptools.package-data] +comfyui = [ + "models/**/*", + "output/**/*", + "temp/**/*", + "input/**/*", + "custom_nodes/**/*", + "*.py", + "api_server/**/*", + "app/**/*", + "comfy/**/*", + "comfy_extras/**/*", + "comfy_execution/**/*", + "utils/**/*", +] + [tool.uv] -# UV-specific configurations (updated May 2025) +# UV-specific configurations python = "3.11" system = false verbosity = 1 threads = "auto" -no-binary = [] -only-binary = [] +lockfile = "UV-req-lock.txt" [tool.uv.dependencies] -# Core dependencies with modern 2025 versions +# Core dependencies redirected to main project dependencies torch = { version = ">=2.3.0", source = "pytorch" } -torchvision = { version = ">=0.18.0", source = "pytorch" } -numpy = ">=2.0.0" -pillow = ">=10.0.0" -aiohttp = ">=3.9.0" -rich = ">=13.6.0" -tqdm = ">=4.66.0" -transformers = ">=4.38.0" -diffusers = ">=0.25.0" -safetensors = ">=0.4.0" [tool.uv.sources] pytorch = { url = "https://download.pytorch.org/whl/cu121" } From bc1cd2546224e097f26f18e8a9f31d600dfb6d2f Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:45:41 +0800 Subject: [PATCH 04/11] feat: add uv package --- cli.py | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 cli.py diff --git a/cli.py b/cli.py new file mode 100644 index 000000000..1acf8f43d --- /dev/null +++ b/cli.py @@ -0,0 +1,122 @@ +#!/usr/bin/env python3 +""" +ComfyUI Command Line Interface +""" + +import os +import sys +import argparse +from pathlib import Path + + +def add_comfyui_to_path(): + """Add the ComfyUI package directory to the Python path.""" + # In development mode, running from source directory + if os.path.exists(os.path.join(os.path.dirname(__file__), "main.py")): + comfyui_path = os.path.dirname(__file__) + else: + # In installed mode, comfyui module path + comfyui_path = os.path.dirname(os.path.abspath(__file__)) + + if comfyui_path not in sys.path: + sys.path.insert(0, comfyui_path) + + +def get_parser(): + """Create and return the argument parser for ComfyUI.""" + parser = argparse.ArgumentParser( + description="ComfyUI - A Stable Diffusion GUI with a graph/nodes interface" + ) + + parser.add_argument( + "--host", type=str, default="127.0.0.1", + help="The host to listen on (default: 127.0.0.1)" + ) + parser.add_argument( + "--port", type=int, default=8188, + help="The port to listen on (default: 8188)" + ) + parser.add_argument( + "--enable-cors-header", type=str, default=None, + help="Enable CORS by setting the Access-Control-Allow-Origin header (default: disabled)" + ) + parser.add_argument( + "--cuda-device", type=int, default=None, + help="The CUDA device to use for inference (default: auto)" + ) + parser.add_argument( + "--disable-cuda-malloc", action="store_true", + help="Force PyTorch to use standard memory allocator instead of cudaMallocAsync" + ) + parser.add_argument( + "--auto-launch", action="store_true", + help="Open the UI in default browser at startup" + ) + parser.add_argument( + "--output-directory", type=str, default=None, + help="Override the default output directory" + ) + parser.add_argument( + "--input-directory", type=str, default=None, + help="Override the default input directory" + ) + parser.add_argument( + "--verbose", action="store_true", + help="Enable verbose logging" + ) + + return parser + + +def main(): + """Main entry point for the ComfyUI application.""" + add_comfyui_to_path() + + parser = get_parser() + args, unknown = parser.parse_known_args() + + # Pass arguments to the original ComfyUI entry point + sys.argv = [sys.argv[0]] + unknown + + # Set environment variables based on arguments + if args.cuda_device is not None: + os.environ['CUDA_VISIBLE_DEVICES'] = str(args.cuda_device) + os.environ['HIP_VISIBLE_DEVICES'] = str(args.cuda_device) + + if args.disable_cuda_malloc: + os.environ['PYTORCH_CUDA_ALLOC_CONF'] = 'backend:cudaMalloc' + + # Import and run the main ComfyUI entry point + import main + + # Override command line arguments with the ones from our parser + import comfy.cli_args + comfy_args = comfy.cli_args.args + + # Set args from our parser to the ComfyUI args object + comfy_args.listen = args.host + comfy_args.port = args.port + comfy_args.enable_cors_header = args.enable_cors_header + comfy_args.cuda_device = args.cuda_device + comfy_args.disable_cuda_malloc = args.disable_cuda_malloc + comfy_args.auto_launch = args.auto_launch + + if args.output_directory: + comfy_args.output_directory = args.output_directory + if args.input_directory: + comfy_args.input_directory = args.input_directory + comfy_args.verbose = args.verbose + + # Start ComfyUI + asyncio_loop, _, start_all_func = main.start_comfyui() + try: + x = start_all_func() + asyncio_loop.run_until_complete(x) + except KeyboardInterrupt: + print("\nStopped server") + + main.cleanup_temp() + + +if __name__ == "__main__": + main() \ No newline at end of file From 4d1fa555fae86246809a12cff670ac4f676e7228 Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:46:22 +0800 Subject: [PATCH 05/11] feat: add UV setup script for ComfyUI installation and environment management --- uv_setup.py | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 uv_setup.py diff --git a/uv_setup.py b/uv_setup.py new file mode 100644 index 000000000..de3a2a7a8 --- /dev/null +++ b/uv_setup.py @@ -0,0 +1,152 @@ +#!/usr/bin/env python3 +""" +UV Setup Script for ComfyUI +""" + +import os +import sys +import subprocess +import argparse +from pathlib import Path + +def check_python_version(): + """Check Python version compatibility.""" + if sys.version_info < (3, 9): + print("ERROR: Python 3.9 or higher is required for ComfyUI.") + sys.exit(1) + +def is_uv_installed(): + """Check if UV is installed.""" + try: + subprocess.run(["uv", "--version"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True) + return True + except (subprocess.SubprocessError, FileNotFoundError): + return False + +def install_uv(): + """Install UV package manager.""" + print("Installing UV package manager...") + try: + if sys.platform == "win32": + subprocess.run( + ["powershell", "-Command", "Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -OutFile install.ps1; ./install.ps1"], + check=True + ) + else: # macOS or Linux + subprocess.run( + ["bash", "-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"], + check=True + ) + + # Update PATH for this session + if sys.platform != "win32": + os.environ["PATH"] = f"{os.path.expanduser('~/.local/bin')}:{os.environ['PATH']}" + + print("โœ“ UV installed successfully.") + return True + except subprocess.SubprocessError: + print("ERROR: UV installation failed.") + return False + +def create_venv(venv_path=".venv"): + """Create a new virtual environment using UV.""" + print(f"Creating virtual environment at {venv_path}...") + try: + subprocess.run(["uv", "venv", venv_path], check=True) + print(f"โœ“ Virtual environment created at {venv_path}.") + return True + except subprocess.SubprocessError: + print("ERROR: Failed to create virtual environment.") + return False + +def install_comfyui(dev_mode=False, gpu=False, advanced=False, lock=False): + """Install ComfyUI using UV.""" + print("Installing ComfyUI...") + + cmd = ["uv", "pip", "install"] + + if dev_mode: + cmd.append("-e") + + # Build extras string + extras = [] + if gpu: + extras.append("gpu") + if advanced: + extras.append("advanced") + if dev_mode: + extras.append("dev") + + if extras: + cmd.append(f".{{{','.join(extras)}}}") + else: + cmd.append(".") + + if lock: + cmd.append("--lock") + + try: + subprocess.run(cmd, check=True) + print("โœ“ ComfyUI installed successfully.") + return True + except subprocess.SubprocessError: + print("ERROR: Failed to install ComfyUI.") + return False + +def print_activation_instructions(venv_path=".venv"): + """Print instructions for activating the virtual environment.""" + print("\nTo activate the virtual environment:") + if sys.platform == "win32": + print(f" {venv_path}\\Scripts\\activate") + else: + print(f" source {venv_path}/bin/activate") + +def print_run_instructions(): + """Print instructions for running ComfyUI.""" + print("\nTo run ComfyUI:") + print(" comfyui") + print("\nOr with options:") + print(" comfyui --host 0.0.0.0 --port 8188 --auto-launch") + +def main(): + parser = argparse.ArgumentParser(description="Set up and install ComfyUI with UV") + parser.add_argument("--no-venv", action="store_true", help="Skip creating a virtual environment") + parser.add_argument("--venv-path", default=".venv", help="Path for the virtual environment (default: .venv)") + parser.add_argument("--dev", action="store_true", help="Install in development mode") + parser.add_argument("--gpu", action="store_true", help="Install with GPU/CUDA support") + parser.add_argument("--advanced", action="store_true", help="Install with advanced dependencies") + parser.add_argument("--lock", action="store_true", help="Generate lockfile during installation") + + args = parser.parse_args() + + # Checks + check_python_version() + + # Install UV if needed + if not is_uv_installed(): + if not install_uv(): + sys.exit(1) + + # Create virtual environment if requested + venv_created = False + if not args.no_venv: + venv_created = create_venv(args.venv_path) + + # Install ComfyUI + install_success = install_comfyui( + dev_mode=args.dev, + gpu=args.gpu, + advanced=args.advanced, + lock=args.lock + ) + + if install_success: + print("\nโœ“ ComfyUI setup completed successfully!") + + if venv_created: + print_activation_instructions(args.venv_path) + + print_run_instructions() + +if __name__ == "__main__": + main() \ No newline at end of file From 5c08b23fa3e83200164164992309118d49ae0f34 Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:47:03 +0800 Subject: [PATCH 06/11] docs: update UV Migration Guide with new installation options and setup instructions --- UV_MIGRATION.md | 153 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 101 insertions(+), 52 deletions(-) diff --git a/UV_MIGRATION.md b/UV_MIGRATION.md index cbf45cf23..279691954 100644 --- a/UV_MIGRATION.md +++ b/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). From a176b07001f5fce920e703f47ed6dd0952d40f1d Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:48:08 +0800 Subject: [PATCH 07/11] refactor: simplify UV setup script by removing environment variable settings and virtual environment checks --- uv_setup.sh | 49 +++++++++---------------------------------------- 1 file changed, 9 insertions(+), 40 deletions(-) diff --git a/uv_setup.sh b/uv_setup.sh index 193d45044..692f8705d 100755 --- a/uv_setup.sh +++ b/uv_setup.sh @@ -1,45 +1,14 @@ #!/bin/bash -# ComfyUI UV Environment Setup Script -# Created: May 2, 2025 +# ComfyUI UV Setup Script -# Set UV environment variables for better performance -export UV_CACHE_DIR="${HOME}/.cache/uv" -export UV_SYSTEM_PYTHON=false -export UV_DEFAULT_PYTHON=3.11 -export UV_THREADS=auto -export UV_VERBOSITY=1 - -# Create directory structure if needed -mkdir -p "${UV_CACHE_DIR}" - -echo "UV environment variables set:" -echo " UV_CACHE_DIR: ${UV_CACHE_DIR}" -echo " UV_DEFAULT_PYTHON: ${UV_DEFAULT_PYTHON}" -echo " UV_THREADS: ${UV_THREADS}" - -# Check if UV is installed -if ! command -v uv >/dev/null 2>&1; then - echo "UV not found. Installing..." - curl -LsSf https://astral.sh/uv/install.sh | sh - - # Add to PATH for this session - source $HOME/.local/bin/env +# Check if Python is available +if ! command -v python3 &> /dev/null; then + echo "Python 3 is required but not found. Please install Python 3.9+ first." + exit 1 fi -# Check for ComfyUI virtual environment -if [ ! -d ".venv" ]; then - echo "Creating virtual environment..." - uv venv - echo "Virtual environment created at .venv" -fi +# Make Python script executable +chmod +x ./uv_setup.py -echo "" -echo "To activate the virtual environment, run:" -echo " source .venv/bin/activate # On Linux/macOS" -echo " .venv\\Scripts\\activate.bat # On Windows" -echo "" -echo "To install/update dependencies:" -echo " ./update_dependencies_uv.py --advanced --cuda --lock" -echo "" -echo "To start ComfyUI:" -echo " python main.py" \ No newline at end of file +# Run the Python setup script with passed arguments +python3 ./uv_setup.py "$@" \ No newline at end of file From 74e61a1bce912fe9719efeb9e03415e11832b4a6 Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:48:16 +0800 Subject: [PATCH 08/11] refactor: enhance dependency update script with improved UV installation checks and error handling --- update_dependencies_uv.py | 157 ++++++++++++++++++++------------------ 1 file changed, 82 insertions(+), 75 deletions(-) diff --git a/update_dependencies_uv.py b/update_dependencies_uv.py index d488bc66b..ebd2a2101 100755 --- a/update_dependencies_uv.py +++ b/update_dependencies_uv.py @@ -1,103 +1,110 @@ #!/usr/bin/env python3 """ -ComfyUI Dependency Update Script using UV -Created: May 2, 2025 +Update dependencies for ComfyUI using UV """ -import argparse import os -import platform -import subprocess import sys +import subprocess +import argparse +from pathlib import Path def check_uv_installed(): - """Check if UV is installed and install if missing.""" + """Check if UV is installed and install it if not.""" try: subprocess.run(["uv", "--version"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True) - print("โœ… UV is installed") - return True - except (subprocess.CalledProcessError, FileNotFoundError): - print("โš ๏ธ UV not found. Installing...") - - if platform.system() == "Windows": - subprocess.run( - ["powershell", "-Command", "Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -OutFile install.ps1; ./install.ps1"], - check=True - ) - else: - subprocess.run( - ["bash", "-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"], - check=True - ) - - print("โœ… UV installed successfully") return True + except (subprocess.SubprocessError, FileNotFoundError): + print("UV not found. Installing UV...") + try: + if sys.platform == "win32": + subprocess.run( + ["powershell", "-Command", "Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -OutFile install.ps1; ./install.ps1"], + check=True + ) + else: # macOS or Linux + subprocess.run( + ["bash", "-c", "curl -LsSf https://astral.sh/uv/install.sh | sh"], + check=True + ) + + # Update PATH for this session + if sys.platform != "win32": + os.environ["PATH"] = f"{os.path.expanduser('~/.local/bin')}:{os.environ['PATH']}" + + print("UV installed successfully.") + return True + except subprocess.SubprocessError: + print("Failed to install UV. Please install manually from https://github.com/astral-sh/uv") + return False -def update_dependencies(args): +def update_dependencies(advanced=False, cuda=False, lock=False): """Update dependencies using UV.""" - # Ensure we're in a virtual environment - if not os.environ.get("VIRTUAL_ENV") and not args.no_venv_check: - print("โš ๏ธ Not running in a virtual environment. Activate one before updating dependencies.") - print("๐Ÿ’ก Run: uv venv && source .venv/bin/activate (or .venv\\Scripts\\activate on Windows)") - if not args.force: + if not check_uv_installed(): + return False + + print("Updating dependencies...") + + # Base dependencies + try: + cmd = ["uv", "pip", "install", "--upgrade", "-r", "requirements.txt"] + if lock: + cmd.append("--lock") + + subprocess.run(cmd, check=True) + print("โœ“ Base dependencies updated successfully.") + except subprocess.SubprocessError: + print("Failed to update base dependencies.") + return False + + # Advanced dependencies if requested + if advanced: + try: + if os.path.exists("requirements_advanced.txt"): + cmd = ["uv", "pip", "install", "--upgrade", "-r", "requirements_advanced.txt"] + if lock: + cmd.append("--lock") + + subprocess.run(cmd, check=True) + print("โœ“ Advanced dependencies updated successfully.") + else: + print("Advanced requirements file not found.") + except subprocess.SubprocessError: + print("Failed to update advanced dependencies.") return False - print("๐Ÿ“ฆ Updating dependencies using UV...") - - # Update base requirements - subprocess.run(["uv", "pip", "install", "--upgrade", "-r", "requirements.txt"], check=True) - print("โœ… Base dependencies updated") - - # Update advanced requirements if requested - if args.advanced: - subprocess.run(["uv", "pip", "install", "--upgrade", "-r", "requirements_advanced.txt"], check=True) - print("โœ… Advanced dependencies updated") - - # Update PyTorch with CUDA if requested - if args.cuda: - torch_version = "2.4.0" if args.latest else "2.3.0" - cuda_version = "12.1" if args.latest else "11.8" + # CUDA dependencies if requested + if cuda: + print("Updating CUDA dependencies...") + extras = ["gpu"] + if advanced: + extras.append("advanced") - print(f"๐Ÿ”„ Installing PyTorch {torch_version} with CUDA {cuda_version}...") - subprocess.run([ - "uv", "pip", "install", "--upgrade", - f"torch=={torch_version}", - f"torchvision>={torch_version}", - f"torchaudio>={torch_version}", - "--index-url", f"https://download.pytorch.org/whl/cu{cuda_version.replace('.', '')}" - ], check=True) - print("โœ… PyTorch updated with CUDA support") - - # Generate lockfile for reproducibility - if args.lock: - print("๐Ÿ”’ Generating lockfile...") - subprocess.run(["uv", "pip", "freeze", ">", "UV-req-lock.txt"], shell=True, check=True) - print("โœ… Lockfile generated: UV-req-lock.txt") + try: + cmd = ["uv", "pip", "install", "--upgrade", f".{{{','.join(extras)}}}"] + if lock: + cmd.append("--lock") + + subprocess.run(cmd, check=True) + print("โœ“ CUDA dependencies updated successfully.") + except subprocess.SubprocessError: + print("Failed to update CUDA dependencies.") + return False return True def main(): - parser = argparse.ArgumentParser(description="Update ComfyUI dependencies using UV") + parser = argparse.ArgumentParser(description="Update ComfyUI dependencies with UV") parser.add_argument("--advanced", action="store_true", help="Update advanced dependencies") - parser.add_argument("--cuda", action="store_true", help="Update PyTorch with CUDA support") - parser.add_argument("--latest", action="store_true", help="Use latest versions (may be less stable)") - parser.add_argument("--lock", action="store_true", help="Generate lockfile after update") - parser.add_argument("--force", action="store_true", help="Force update even if not in venv") - parser.add_argument("--no-venv-check", action="store_true", help="Skip virtual environment check") + parser.add_argument("--cuda", action="store_true", help="Update CUDA dependencies") + parser.add_argument("--lock", action="store_true", help="Generate lockfile during update") args = parser.parse_args() - print("ComfyUI Dependency Update") - print("========================") - - if not check_uv_installed(): - sys.exit(1) - - if update_dependencies(args): - print("\nโœจ Dependencies updated successfully!") - print("\n๐Ÿ’ก To start ComfyUI, run: python main.py") + if update_dependencies(args.advanced, args.cuda, args.lock): + print("\nโœ“ All dependencies updated successfully!") else: - print("\nโŒ Dependency update failed or was skipped") + print("\nโŒ Failed to update some dependencies.") sys.exit(1) if __name__ == "__main__": From 219ee6a92338c510f5722d871ded01d7425f5c1d Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:57:47 +0800 Subject: [PATCH 09/11] docs: add comprehensive installation and user guide for ComfyUI --- README.md | 442 +++++-------------------------------------- docs/INSTALL.md | 0 docs/UV_PACKAGE.md | 0 docs/installation.md | 162 ++++++++++++++++ docs/user-guide.md | 194 +++++++++++++++++++ 5 files changed, 402 insertions(+), 396 deletions(-) create mode 100644 docs/INSTALL.md create mode 100644 docs/UV_PACKAGE.md create mode 100644 docs/installation.md create mode 100644 docs/user-guide.md diff --git a/README.md b/README.md index 92e014a69..4234582f6 100644 --- a/README.md +++ b/README.md @@ -1,424 +1,74 @@
# ComfyUI -**The most powerful and modular visual AI engine and application.** +**A powerful and modular stable diffusion GUI with a graph/nodes interface.** - -[![Website][website-shield]][website-url] -[![Dynamic JSON Badge][discord-shield]][discord-url] -[![Matrix][matrix-shield]][matrix-url] -
-[![][github-release-shield]][github-release-link] -[![][github-release-date-shield]][github-release-link] -[![][github-downloads-shield]][github-downloads-link] -[![][github-downloads-latest-shield]][github-downloads-link] - -[matrix-shield]: https://img.shields.io/badge/Matrix-000000?style=flat&logo=matrix&logoColor=white -[matrix-url]: https://app.element.io/#/room/%23comfyui_space%3Amatrix.org -[website-shield]: https://img.shields.io/badge/ComfyOrg-4285F4?style=flat -[website-url]: https://www.comfy.org/ - -[discord-shield]: https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fdiscord.com%2Fapi%2Finvites%2Fcomfyorg%3Fwith_counts%3Dtrue&query=%24.approximate_member_count&logo=discord&logoColor=white&label=Discord&color=green&suffix=%20total -[discord-url]: https://www.comfy.org/discord - -[github-release-shield]: https://img.shields.io/github/v/release/comfyanonymous/ComfyUI?style=flat&sort=semver -[github-release-link]: https://github.com/comfyanonymous/ComfyUI/releases -[github-release-date-shield]: https://img.shields.io/github/release-date/comfyanonymous/ComfyUI?style=flat -[github-downloads-shield]: https://img.shields.io/github/downloads/comfyanonymous/ComfyUI/total?style=flat -[github-downloads-latest-shield]: https://img.shields.io/github/downloads/comfyanonymous/ComfyUI/latest/total?style=flat&label=downloads%40latest -[github-downloads-link]: https://github.com/comfyanonymous/ComfyUI/releases - -![ComfyUI Screenshot](https://github.com/user-attachments/assets/7ccaf2c1-9b72-41ae-9a89-5688c94b7abe) +![ComfyUI Screenshot](https://comfyanonymous.github.io/ComfyUI_examples/comfyui_screenshot.png)
-ComfyUI lets you design and execute advanced stable diffusion pipelines using a graph/nodes/flowchart based interface. Available on Windows, Linux, and macOS. +## Quick Start -## Get Started +### Option 1: Install as a Package (New!) -#### [Desktop Application](https://www.comfy.org/download) -- The easiest way to get started. -- Available on Windows & macOS. - -#### [Windows Portable Package](#installing) -- Get the latest commits and completely portable. -- Available on Windows. - -#### [Manual Install](#manual-install-windows-linux) -Supports all operating systems and GPU types (NVIDIA, AMD, Intel, Apple Silicon, Ascend). - -## [Examples](https://comfyanonymous.github.io/ComfyUI_examples/) -See what ComfyUI can do with the [example workflows](https://comfyanonymous.github.io/ComfyUI_examples/). - -## Features -- Nodes/graph/flowchart interface to experiment and create complex Stable Diffusion workflows without needing to code anything. -- Image Models - - SD1.x, SD2.x, - - [SDXL](https://comfyanonymous.github.io/ComfyUI_examples/sdxl/), [SDXL Turbo](https://comfyanonymous.github.io/ComfyUI_examples/sdturbo/) - - [Stable Cascade](https://comfyanonymous.github.io/ComfyUI_examples/stable_cascade/) - - [SD3 and SD3.5](https://comfyanonymous.github.io/ComfyUI_examples/sd3/) - - Pixart Alpha and Sigma - - [AuraFlow](https://comfyanonymous.github.io/ComfyUI_examples/aura_flow/) - - [HunyuanDiT](https://comfyanonymous.github.io/ComfyUI_examples/hunyuan_dit/) - - [Flux](https://comfyanonymous.github.io/ComfyUI_examples/flux/) - - [Lumina Image 2.0](https://comfyanonymous.github.io/ComfyUI_examples/lumina2/) - - [HiDream](https://comfyanonymous.github.io/ComfyUI_examples/hidream/) -- Video Models - - [Stable Video Diffusion](https://comfyanonymous.github.io/ComfyUI_examples/video/) - - [Mochi](https://comfyanonymous.github.io/ComfyUI_examples/mochi/) - - [LTX-Video](https://comfyanonymous.github.io/ComfyUI_examples/ltxv/) - - [Hunyuan Video](https://comfyanonymous.github.io/ComfyUI_examples/hunyuan_video/) - - [Nvidia Cosmos](https://comfyanonymous.github.io/ComfyUI_examples/cosmos/) - - [Wan 2.1](https://comfyanonymous.github.io/ComfyUI_examples/wan/) -- 3D Models - - [Hunyuan3D 2.0](https://docs.comfy.org/tutorials/3d/hunyuan3D-2) -- [Stable Audio](https://comfyanonymous.github.io/ComfyUI_examples/audio/) -- Asynchronous Queue system -- Many optimizations: Only re-executes the parts of the workflow that changes between executions. -- Smart memory management: can automatically run models on GPUs with as low as 1GB vram. -- Works even if you don't have a GPU with: ```--cpu``` (slow) -- Can load ckpt, safetensors and diffusers models/checkpoints. Standalone VAEs and CLIP models. -- Embeddings/Textual inversion -- [Loras (regular, locon and loha)](https://comfyanonymous.github.io/ComfyUI_examples/lora/) -- [Hypernetworks](https://comfyanonymous.github.io/ComfyUI_examples/hypernetworks/) -- Loading full workflows (with seeds) from generated PNG, WebP and FLAC files. -- Saving/Loading workflows as Json files. -- Nodes interface can be used to create complex workflows like one for [Hires fix](https://comfyanonymous.github.io/ComfyUI_examples/2_pass_txt2img/) or much more advanced ones. -- [Area Composition](https://comfyanonymous.github.io/ComfyUI_examples/area_composition/) -- [Inpainting](https://comfyanonymous.github.io/ComfyUI_examples/inpaint/) with both regular and inpainting models. -- [ControlNet and T2I-Adapter](https://comfyanonymous.github.io/ComfyUI_examples/controlnet/) -- [Upscale Models (ESRGAN, ESRGAN variants, SwinIR, Swin2SR, etc...)](https://comfyanonymous.github.io/ComfyUI_examples/upscale_models/) -- [unCLIP Models](https://comfyanonymous.github.io/ComfyUI_examples/unclip/) -- [GLIGEN](https://comfyanonymous.github.io/ComfyUI_examples/gligen/) -- [Model Merging](https://comfyanonymous.github.io/ComfyUI_examples/model_merging/) -- [LCM models and Loras](https://comfyanonymous.github.io/ComfyUI_examples/lcm/) -- Latent previews with [TAESD](#how-to-show-high-quality-previews) -- Starts up very fast. -- Works fully offline: will never download anything. -- [Config file](extra_model_paths.yaml.example) to set the search paths for models. - -Workflow examples can be found on the [Examples page](https://comfyanonymous.github.io/ComfyUI_examples/) - -## Release Process - -ComfyUI follows a weekly release cycle every Friday, with three interconnected repositories: - -1. **[ComfyUI Core](https://github.com/comfyanonymous/ComfyUI)** - - Releases a new stable version (e.g., v0.7.0) - - Serves as the foundation for the desktop release - -2. **[ComfyUI Desktop](https://github.com/Comfy-Org/desktop)** - - Builds a new release using the latest stable core version - - Version numbers match the core release (e.g., Desktop v1.7.0 uses Core v1.7.0) - -3. **[ComfyUI Frontend](https://github.com/Comfy-Org/ComfyUI_frontend)** - - Weekly frontend updates are merged into the core repository - - Features are frozen for the upcoming core release - - Development continues for the next release cycle - -## Shortcuts - -| Keybind | Explanation | -|------------------------------------|--------------------------------------------------------------------------------------------------------------------| -| `Ctrl` + `Enter` | Queue up current graph for generation | -| `Ctrl` + `Shift` + `Enter` | Queue up current graph as first for generation | -| `Ctrl` + `Alt` + `Enter` | Cancel current generation | -| `Ctrl` + `Z`/`Ctrl` + `Y` | Undo/Redo | -| `Ctrl` + `S` | Save workflow | -| `Ctrl` + `O` | Load workflow | -| `Ctrl` + `A` | Select all nodes | -| `Alt `+ `C` | Collapse/uncollapse selected nodes | -| `Ctrl` + `M` | Mute/unmute selected nodes | -| `Ctrl` + `B` | Bypass selected nodes (acts like the node was removed from the graph and the wires reconnected through) | -| `Delete`/`Backspace` | Delete selected nodes | -| `Ctrl` + `Backspace` | Delete the current graph | -| `Space` | Move the canvas around when held and moving the cursor | -| `Ctrl`/`Shift` + `Click` | Add clicked node to selection | -| `Ctrl` + `C`/`Ctrl` + `V` | Copy and paste selected nodes (without maintaining connections to outputs of unselected nodes) | -| `Ctrl` + `C`/`Ctrl` + `Shift` + `V` | Copy and paste selected nodes (maintaining connections from outputs of unselected nodes to inputs of pasted nodes) | -| `Shift` + `Drag` | Move multiple selected nodes at the same time | -| `Ctrl` + `D` | Load default graph | -| `Alt` + `+` | Canvas Zoom in | -| `Alt` + `-` | Canvas Zoom out | -| `Ctrl` + `Shift` + LMB + Vertical drag | Canvas Zoom in/out | -| `P` | Pin/Unpin selected nodes | -| `Ctrl` + `G` | Group selected nodes | -| `Q` | Toggle visibility of the queue | -| `H` | Toggle visibility of history | -| `R` | Refresh graph | -| `F` | Show/Hide menu | -| `.` | Fit view to selection (Whole graph when nothing is selected) | -| Double-Click LMB | Open node quick search palette | -| `Shift` + Drag | Move multiple wires at once | -| `Ctrl` + `Alt` + LMB | Disconnect all wires from clicked slot | - -`Ctrl` can also be replaced with `Cmd` instead for macOS users - -# Installing - -## Windows Portable - -There is a portable standalone build for Windows that should work for running on Nvidia GPUs or for running on your CPU only on the [releases page](https://github.com/comfyanonymous/ComfyUI/releases). - -### [Direct link to download](https://github.com/comfyanonymous/ComfyUI/releases/latest/download/ComfyUI_windows_portable_nvidia.7z) - -Simply download, extract with [7-Zip](https://7-zip.org) and run. Make sure you put your Stable Diffusion checkpoints/models (the huge ckpt/safetensors files) in: ComfyUI\models\checkpoints - -If you have trouble extracting it, right click the file -> properties -> unblock - -#### How do I share models between another UI and ComfyUI? - -See the [Config file](extra_model_paths.yaml.example) to set the search paths for models. In the standalone windows build you can find this file in the ComfyUI directory. Rename this file to extra_model_paths.yaml and edit it with your favorite text editor. - -## Jupyter Notebook - -To run it on services like paperspace, kaggle or colab you can use my [Jupyter Notebook](notebooks/comfyui_colab.ipynb) - - -## [comfy-cli](https://docs.comfy.org/comfy-cli/getting-started) - -You can install and start ComfyUI using comfy-cli: ```bash -pip install comfy-cli -comfy install +# Install ComfyUI with GPU support +uv pip install "comfyui[gpu]" + +# Run ComfyUI +comfyui ``` -## Manual Install (Windows, Linux) +### Option 2: From Source -python 3.13 is supported but using 3.12 is recommended because some custom nodes and their dependencies might not support it yet. +```bash +# Clone the repository +git clone https://github.com/comfyanonymous/ComfyUI.git +cd ComfyUI -Git clone this repo. +# Set up with UV (recommended) +./uv_setup.sh --gpu -Put your SD checkpoints (the huge ckpt/safetensors files) in: models/checkpoints +# Or on Windows: +python uv_setup.py --gpu -Put your VAE in: models/vae - -## Installation Options - -### Option 1: Install with UV (Recommended) - -*Added 2025-05-02* - -[UV](https://github.com/astral-sh/uv) is a faster, more reliable Python package installer that we now recommend for ComfyUI. - -1. **Install UV**: - ```bash - curl -LsSf https://astral.sh/uv/install.sh | sh - source $HOME/.local/bin/env # For bash/zsh - ``` - -2. **Install ComfyUI dependencies**: - ```bash - # Create and activate virtual environment - uv venv - source .venv/bin/activate # Linux/macOS - # or - .venv\Scripts\activate # Windows - - # Install dependencies - uv pip install -r requirements.txt - ``` - -For detailed instructions on using UV with ComfyUI, see our [UV Migration Guide](UV_MIGRATION.md). - -### Option 2: Install with pip (Traditional) - -### AMD GPUs (Linux only) -AMD users can install rocm and pytorch with pip if you don't have it already installed, this is the command to install the stable version: - -```pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.2.4``` - -This is the command to install the nightly with ROCm 6.3 which might have some performance improvements: - -```pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm6.3``` - -### Intel GPUs (Windows and Linux) - -(Option 1) Intel Arc GPU users can install native PyTorch with torch.xpu support using pip (currently available in PyTorch nightly builds). More information can be found [here](https://pytorch.org/docs/main/notes/get_start_xpu.html) - -1. To install PyTorch nightly, use the following command: - -```pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/xpu``` - -2. Launch ComfyUI by running `python main.py` - - -(Option 2) Alternatively, Intel GPUs supported by Intel Extension for PyTorch (IPEX) can leverage IPEX for improved performance. - -1. For Intelยฎ Arcโ„ข A-Series Graphics utilizing IPEX, create a conda environment and use the commands below: - -``` -conda install libuv -pip install torch==2.3.1.post0+cxx11.abi torchvision==0.18.1.post0+cxx11.abi torchaudio==2.3.1.post0+cxx11.abi intel-extension-for-pytorch==2.3.110.post0+xpu --extra-index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/us/ --extra-index-url https://pytorch-extension.intel.com/release-whl/stable/xpu/cn/ +# Run ComfyUI +python main.py ``` -For other supported Intel GPUs with IPEX, visit [Installation](https://intel.github.io/intel-extension-for-pytorch/index.html#installation?platform=gpu) for more information. +## Main Features -Additional discussion and help can be found [here](https://github.com/comfyanonymous/ComfyUI/discussions/476). +- Nodes/graph/flowchart-based UI +- Highly optimized for better performance and VRAM usage +- Advanced prompt system with wildcards and more +- Create and share workflows as JSON files +- Supports multiple model backends +- Powerful API for external integration +- Extensible with custom nodes -### NVIDIA +## Requirements -Nvidia users should install stable pytorch using this command: +- Python 3.9+ (Python 3.11 recommended) +- GPU with at least 4GB VRAM (8GB+ recommended) +- [Optional] CUDA-compatible NVIDIA GPU for faster processing -```pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu128``` +## Documentation -This is the command to install pytorch nightly instead which might have performance improvements. +- [Installation Guide](docs/installation.md) +- [User Guide](docs/user-guide.md) +- [API Documentation](docs/api.md) +- [Custom Nodes Guide](docs/custom-nodes.md) +- [UV Migration Guide](UV_MIGRATION.md) -```pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu128``` +## Contributing -#### Troubleshooting +Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting pull requests. -If you get the "Torch not compiled with CUDA enabled" error, uninstall torch with: +## License -```pip uninstall torch``` +ComfyUI is licensed under the GNU General Public License v3.0. -And install it again with the command above. +## Community -### Dependencies - -Install the dependencies by opening your terminal inside the ComfyUI folder and: - -```pip install -r requirements.txt``` - -After this you should have everything installed and can proceed to running ComfyUI. - -### Others: - -#### Apple Mac silicon - -You can install ComfyUI in Apple Mac silicon (M1 or M2) with any recent macOS version. - -1. Install pytorch nightly. For instructions, read the [Accelerated PyTorch training on Mac](https://developer.apple.com/metal/pytorch/) Apple Developer guide (make sure to install the latest pytorch nightly). -1. Follow the [ComfyUI manual installation](#manual-install-windows-linux) instructions for Windows and Linux. -1. Install the ComfyUI [dependencies](#dependencies). If you have another Stable Diffusion UI [you might be able to reuse the dependencies](#i-already-have-another-ui-for-stable-diffusion-installed-do-i-really-have-to-install-all-of-these-dependencies). -1. Launch ComfyUI by running `python main.py` - -> **Note**: Remember to add your models, VAE, LoRAs etc. to the corresponding Comfy folders, as discussed in [ComfyUI manual installation](#manual-install-windows-linux). - -#### DirectML (AMD Cards on Windows) - -```pip install torch-directml``` Then you can launch ComfyUI with: ```python main.py --directml``` - -#### Ascend NPUs - -For models compatible with Ascend Extension for PyTorch (torch_npu). To get started, ensure your environment meets the prerequisites outlined on the [installation](https://ascend.github.io/docs/sources/ascend/quick_install.html) page. Here's a step-by-step guide tailored to your platform and installation method: - -1. Begin by installing the recommended or newer kernel version for Linux as specified in the Installation page of torch-npu, if necessary. -2. Proceed with the installation of Ascend Basekit, which includes the driver, firmware, and CANN, following the instructions provided for your specific platform. -3. Next, install the necessary packages for torch-npu by adhering to the platform-specific instructions on the [Installation](https://ascend.github.io/docs/sources/pytorch/install.html#pytorch) page. -4. Finally, adhere to the [ComfyUI manual installation](#manual-install-windows-linux) guide for Linux. Once all components are installed, you can run ComfyUI as described earlier. - -#### Cambricon MLUs - -For models compatible with Cambricon Extension for PyTorch (torch_mlu). Here's a step-by-step guide tailored to your platform and installation method: - -1. Install the Cambricon CNToolkit by adhering to the platform-specific instructions on the [Installation](https://www.cambricon.com/docs/sdk_1.15.0/cntoolkit_3.7.2/cntoolkit_install_3.7.2/index.html) -2. Next, install the PyTorch(torch_mlu) following the instructions on the [Installation](https://www.cambricon.com/docs/sdk_1.15.0/cambricon_pytorch_1.17.0/user_guide_1.9/index.html) -3. Launch ComfyUI by running `python main.py` - -# Running - -```python main.py``` - -### For AMD cards not officially supported by ROCm - -Try running it with this command if you have issues: - -For 6700, 6600 and maybe other RDNA2 or older: ```HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py``` - -For AMD 7600 and maybe other RDNA3 cards: ```HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py``` - -### AMD ROCm Tips - -You can enable experimental memory efficient attention on pytorch 2.5 in ComfyUI on RDNA3 and potentially other AMD GPUs using this command: - -```TORCH_ROCM_AOTRITON_ENABLE_EXPERIMENTAL=1 python main.py --use-pytorch-cross-attention``` - -You can also try setting this env variable `PYTORCH_TUNABLEOP_ENABLED=1` which might speed things up at the cost of a very slow initial run. - -# Notes - -Only parts of the graph that have an output with all the correct inputs will be executed. - -Only parts of the graph that change from each execution to the next will be executed, if you submit the same graph twice only the first will be executed. If you change the last part of the graph only the part you changed and the part that depends on it will be executed. - -Dragging a generated png on the webpage or loading one will give you the full workflow including seeds that were used to create it. - -You can use () to change emphasis of a word or phrase like: (good code:1.2) or (bad code:0.8). The default emphasis for () is 1.1. To use () characters in your actual prompt escape them like \\( or \\). - -You can use {day|night}, for wildcard/dynamic prompts. With this syntax "{wild|card|test}" will be randomly replaced by either "wild", "card" or "test" by the frontend every time you queue the prompt. To use {} characters in your actual prompt escape them like: \\{ or \\}. - -Dynamic prompts also support C-style comments, like `// comment` or `/* comment */`. - -To use a textual inversion concepts/embeddings in a text prompt put them in the models/embeddings directory and use them in the CLIPTextEncode node like this (you can omit the .pt extension): - -```embedding:embedding_filename.pt``` - - -## How to show high-quality previews? - -Use ```--preview-method auto``` to enable previews. - -The default installation includes a fast latent preview method that's low-resolution. To enable higher-quality previews with [TAESD](https://github.com/madebyollin/taesd), download the [taesd_decoder.pth, taesdxl_decoder.pth, taesd3_decoder.pth and taef1_decoder.pth](https://github.com/madebyollin/taesd/) and place them in the `models/vae_approx` folder. Once they're installed, restart ComfyUI and launch it with `--preview-method taesd` to enable high-quality previews. - -## How to use TLS/SSL? -Generate a self-signed certificate (not appropriate for shared/production use) and key by running the command: `openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"` - -Use `--tls-keyfile key.pem --tls-certfile cert.pem` to enable TLS/SSL, the app will now be accessible with `https://...` instead of `http://...`. - -> Note: Windows users can use [alexisrolland/docker-openssl](https://github.com/alexisrolland/docker-openssl) or one of the [3rd party binary distributions](https://wiki.openssl.org/index.php/Binaries) to run the command example above. -

If you use a container, note that the volume mount `-v` can be a relative path so `... -v ".\:/openssl-certs" ...` would create the key & cert files in the current directory of your command prompt or powershell terminal. - -## Support and dev channel - -[Discord](https://comfy.org/discord): Try the #help or #feedback channels. - -[Matrix space: #comfyui_space:matrix.org](https://app.element.io/#/room/%23comfyui_space%3Amatrix.org) (it's like discord but open source). - -See also: [https://www.comfy.org/](https://www.comfy.org/) - -## Frontend Development - -As of August 15, 2024, we have transitioned to a new frontend, which is now hosted in a separate repository: [ComfyUI Frontend](https://github.com/Comfy-Org/ComfyUI_frontend). This repository now hosts the compiled JS (from TS/Vue) under the `web/` directory. - -### Reporting Issues and Requesting Features - -For any bugs, issues, or feature requests related to the frontend, please use the [ComfyUI Frontend repository](https://github.com/Comfy-Org/ComfyUI_frontend). This will help us manage and address frontend-specific concerns more efficiently. - -### Using the Latest Frontend - -The new frontend is now the default for ComfyUI. However, please note: - -1. The frontend in the main ComfyUI repository is updated fortnightly. -2. Daily releases are available in the separate frontend repository. - -To use the most up-to-date frontend version: - -1. For the latest daily release, launch ComfyUI with this command line argument: - - ``` - --front-end-version Comfy-Org/ComfyUI_frontend@latest - ``` - -2. For a specific version, replace `latest` with the desired version number: - - ``` - --front-end-version Comfy-Org/ComfyUI_frontend@1.2.2 - ``` - -This approach allows you to easily switch between the stable fortnightly release and the cutting-edge daily updates, or even specific versions for testing purposes. - -### Accessing the Legacy Frontend - -If you need to use the legacy frontend for any reason, you can access it using the following command line argument: - -``` ---front-end-version Comfy-Org/ComfyUI_legacy_frontend@latest -``` - -This will use a snapshot of the legacy frontend preserved in the [ComfyUI Legacy Frontend repository](https://github.com/Comfy-Org/ComfyUI_legacy_frontend). - -# QA - -### Which GPU should I buy for this? - -[See this page for some recommendations](https://github.com/comfyanonymous/ComfyUI/wiki/Which-GPU-should-I-buy-for-ComfyUI) +- [Discord Server](https://comfy.org/discord) +- [GitHub Issues](https://github.com/comfyanonymous/ComfyUI/issues) +- [Examples Repository](https://github.com/comfyanonymous/ComfyUI_examples) diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/UV_PACKAGE.md b/docs/UV_PACKAGE.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 000000000..72307f9b7 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,162 @@ +# Installation Guide + +This document provides detailed instructions for installing ComfyUI using different methods. + +## Table of Contents +- [System Requirements](#system-requirements) +- [Installation Methods](#installation-methods) + - [Option 1: Install as a Package (Recommended)](#option-1-install-as-a-package-recommended) + - [Option 2: Install from Source](#option-2-install-from-source) + - [Option 3: Docker Installation](#option-3-docker-installation) +- [GPU Setup](#gpu-setup) +- [Troubleshooting](#troubleshooting) + +## System Requirements + +### Minimum Requirements +- Python 3.9 or newer (Python 3.11 recommended) +- NVIDIA GPU with at least 4GB VRAM +- 8GB RAM +- 2GB free disk space + +### Recommended Specifications +- Python 3.11 +- NVIDIA GPU with 8GB+ VRAM (RTX series recommended) +- 16GB RAM +- SSD with 10GB+ free space + +## Installation Methods + +### Option 1: Install as a Package (Recommended) + +The package installation method is the simplest way to get started with ComfyUI. + +#### Install with UV (Fastest) + +[UV](https://github.com/astral-sh/uv) is a fast, reliable package manager for Python. We recommend using it for the best installation experience: + +```bash +# Install UV if you don't have it +curl -LsSf https://astral.sh/uv/install.sh | sh + +# Create and activate a virtual environment +uv venv .venv +source .venv/bin/activate # On Linux/macOS +# OR +.venv\Scripts\activate # On Windows + +# Install ComfyUI with GPU support +uv pip install "comfyui[gpu]" + +# Run ComfyUI +comfyui +``` + +#### Install with Pip + +If you prefer using standard pip: + +```bash +# Create and activate a virtual environment +python -m venv venv +source venv/bin/activate # On Linux/macOS +# OR +venv\Scripts\activate # On Windows + +# Install ComfyUI +pip install "comfyui[gpu]" + +# Run ComfyUI +comfyui +``` + +### Option 2: Install from Source + +Installing from source gives you the latest development version and more control over the installation process. + +```bash +# Clone the repository +git clone https://github.com/comfyanonymous/ComfyUI.git +cd ComfyUI + +# Method A: Use the setup script (recommended) +python uv_setup.py --gpu --advanced + +# Method B: Manual installation +# 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 + +# Run ComfyUI +python main.py +``` + +### Option 3: Docker Installation + +For users who prefer containerized applications: + +```bash +# Pull and run the ComfyUI Docker image +docker pull comfyanonymous/comfyui:latest +docker run -p 8188:8188 -v /path/to/models:/app/models comfyanonymous/comfyui:latest +``` + +## GPU Setup + +### NVIDIA GPUs + +ComfyUI works best with NVIDIA GPUs using CUDA. To leverage GPU acceleration: + +1. Ensure you have the latest NVIDIA drivers installed +2. Install the CUDA-enabled version of ComfyUI: + ```bash + uv pip install "comfyui[gpu]" + ``` + +### AMD GPUs + +For AMD GPUs, follow these additional steps: + +1. Install ROCm (for compatible AMD GPUs) +2. Install PyTorch with ROCm support +3. Configure ComfyUI for AMD GPU usage: + ```bash + python main.py --use-rocm + ``` + +## Troubleshooting + +### Common Issues + +#### CUDA Out of Memory +If you encounter CUDA out of memory errors: +- Try using `--disable-cuda-malloc` flag +- Lower model precision using the `--fp16` flag +- Use smaller-sized models + +#### Missing Dependencies +If you encounter missing dependencies: +```bash +uv pip install --upgrade -r requirements.txt +``` + +#### Package Conflicts +If you have conflicting packages: +```bash +uv pip install --force-reinstall "comfyui[gpu]" +``` + +### Getting Help + +If you encounter issues not covered here: +- Check the [Discord server](https://comfy.org/discord) for community support +- Search for similar issues in the [GitHub repository](https://github.com/comfyanonymous/ComfyUI/issues) +- Run with `--verbose` flag for detailed logs: + ```bash + comfyui --verbose + ``` \ No newline at end of file diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 000000000..ebb61982b --- /dev/null +++ b/docs/user-guide.md @@ -0,0 +1,194 @@ +# User Guide + +This document provides detailed information on how to use ComfyUI effectively. + +## Table of Contents +- [Getting Started](#getting-started) +- [Interface Overview](#interface-overview) +- [Working with Nodes](#working-with-nodes) +- [Managing Models](#managing-models) +- [Creating Workflows](#creating-workflows) +- [Advanced Features](#advanced-features) +- [Best Practices](#best-practices) + +## Getting Started + +After installing ComfyUI, you can access it via your web browser: + +1. Start ComfyUI: + ```bash + comfyui + # OR if installed from source + python main.py + ``` + +2. Open your web browser and navigate to: + ``` + http://localhost:8188 + ``` + +3. ComfyUI will load with an empty workspace where you can create your nodes and workflow. + +## Interface Overview + +### Main Areas + +- **Canvas**: The main area where you create and connect nodes +- **Node Menu**: Left sidebar with available nodes categorized by function +- **Settings**: Access global settings via the gear icon in the top right +- **Queue**: View and manage processing queue in the top panel + +### Navigation + +- **Pan**: Middle mouse button or Alt + Left mouse button +- **Zoom**: Mouse wheel or Ctrl + Mouse wheel +- **Select multiple nodes**: Drag a selection box or Shift + Click +- **Move nodes**: Drag selected nodes +- **Delete nodes**: Select and press Delete key + +## Working with Nodes + +### Node Basics + +Nodes are the building blocks of ComfyUI workflows. Each node performs a specific function and can be connected to other nodes. + +#### Node Types + +- **Input Nodes**: Provide data (text prompts, images, etc.) +- **Processing Nodes**: Transform data (models, samplers, conditioning) +- **Output Nodes**: Generate results (images, videos, latents) +- **Utility Nodes**: Helper functions (math, logic, conversion) + +#### Creating Nodes + +1. Right-click on the canvas +2. Navigate through the menu categories +3. Click on the node you want to add +4. Alternatively, use the Quick Node Search with Ctrl+Space + +#### Connecting Nodes + +1. Click and drag from an output socket (right side) +2. Connect to an input socket (left side) +3. Compatible connections will be highlighted +4. Incompatible connections will be rejected + +### Node Properties + +Each node has properties that can be configured: + +1. Click on a node to select it +2. Adjust parameters in the property panel +3. Some parameters support dynamic values via connections + +## Managing Models + +ComfyUI supports various AI models for different purposes. + +### Model Types + +- **Checkpoints**: Main Stable Diffusion models +- **LoRA**: Style adaptations and fine-tuning +- **Textual Inversions/Embeddings**: Concept encodings +- **VAE**: Variational autoencoders for encoding/decoding +- **CLIP**: Text encoders for prompts +- **ControlNet**: Models for guided image generation + +### Loading Models + +Models can be loaded via dedicated nodes: + +1. Add the appropriate model loader node +2. Select your model from the dropdown +3. Connect to other nodes that require the model + +### Model Management + +- Models are stored in the `models` directory +- Subdirectories organize different model types +- Add new models by placing them in the appropriate folder +- ComfyUI automatically detects new models on startup + +## Creating Workflows + +### Basic Workflow + +A minimal image generation workflow consists of: + +1. **Checkpoint Loader**: Load a model +2. **CLIP Text Encode**: Process positive and negative prompts +3. **KSampler**: Configure sampling parameters +4. **VAE Decode**: Convert latent representation to image +5. **Save Image**: Output the generated image + +### Workflow Management + +- **Save Workflow**: Click "Save" to download JSON workflow file +- **Load Workflow**: Click "Load" to import a workflow +- **Share Workflows**: Exchange JSON files with others +- **API Access**: Workflows can be executed via API + +### Workflow Templates + +ComfyUI includes templates for common tasks: + +1. Click "Load" to access templates +2. Select a template that matches your need +3. Modify parameters to customize the results + +## Advanced Features + +### Batching + +Process multiple images with one workflow: + +1. Use batch size parameter in sampler nodes +2. Use Empty Latent Image with multiple batches +3. Process results with Latent from Batch node + +### Animation + +Create animations using keyframes or video input: + +1. Use Animate Diff or similar animation nodes +2. Configure frames, motion, and interpolation +3. Output video or image sequence + +### Upscaling + +Enhance resolution of generated images: + +1. Generate base image +2. Feed into upscaler node (Lanczos, ESRGAN, etc.) +3. Configure scale factor and parameters +4. Save higher resolution result + +## Best Practices + +### Performance Optimization + +- Use half-precision (fp16) for faster processing +- Adjust VRAM usage in settings +- Process at lower resolution and upscale later +- Use VAE tiling for large images + +### Workflow Organization + +- Group related nodes for clarity +- Add comment nodes to document workflows +- Use consistent naming conventions +- Break complex workflows into subgraphs + +### Common Pitfalls + +- Ensure compatible node connections +- Watch VRAM usage for larger models +- Backup workflows regularly +- Check error messages in console log + +### Getting Help + +- Hover over node inputs/outputs for tooltips +- Check documentation for specific nodes +- Visit Discord community for support +- Explore shared workflows for examples \ No newline at end of file From ce337af0267a9aea2398885aed5d10aa55f8dc5f Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:58:34 +0800 Subject: [PATCH 10/11] docs: add comprehensive API documentation for ComfyUI --- docs/api.md | 411 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 411 insertions(+) create mode 100644 docs/api.md diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 000000000..aa5d01e91 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,411 @@ +# API Documentation + +This document provides detailed information about the ComfyUI API for developers wanting to integrate with or automate ComfyUI. + +## Table of Contents +- [API Overview](#api-overview) +- [REST API Endpoints](#rest-api-endpoints) +- [WebSocket API](#websocket-api) +- [Python SDK](#python-sdk) +- [Examples](#examples) +- [Best Practices](#best-practices) + +## API Overview + +ComfyUI provides a comprehensive API that allows for: +- Executing workflows +- Retrieving generated images +- Managing models +- Monitoring task status +- Controlling the server + +The API is accessible via HTTP REST endpoints and WebSocket for real-time updates. + +## REST API Endpoints + +### Server Information + +#### Get System Stats +``` +GET /system_stats +``` +Returns system information including RAM, VRAM, Python version, and PyTorch version. + +#### Get Object Info +``` +GET /object_info +``` +Returns information about all available nodes. + +#### Get Object Info for Specific Node +``` +GET /object_info/{node_class} +``` +Returns information about a specific node class. + +### Workflow Execution + +#### Execute Workflow +``` +POST /prompt +``` +Execute a workflow with the given prompt. + +**Request Body:** +```json +{ + "prompt": { + // Workflow JSON + }, + "client_id": "optional_client_id" +} +``` + +**Response:** +```json +{ + "prompt_id": "uuid", + "number": 1, + "node_errors": {} +} +``` + +#### Get Execution History +``` +GET /history +``` +Returns execution history. + +#### Get Specific Execution +``` +GET /history/{prompt_id} +``` +Returns details of a specific execution. + +### Queue Management + +#### Get Queue +``` +GET /queue +``` +Returns the current execution queue. + +#### Modify Queue +``` +POST /queue +``` +Modify the execution queue (clear or delete items). + +**Request Body:** +```json +{ + "clear": true, + "delete": ["prompt_id1", "prompt_id2"] +} +``` + +#### Interrupt Processing +``` +POST /interrupt +``` +Interrupts the current processing task. + +### Model Management + +#### Get Available Models +``` +GET /models +``` +Returns a list of available model types. + +#### Get Models of a Specific Type +``` +GET /models/{folder} +``` +Returns a list of available models in the specified folder. + +#### View Model Metadata +``` +GET /view_metadata/{folder_name}?filename=model.safetensors +``` +Returns metadata for a specific model file. + +### File Operations + +#### Upload Image +``` +POST /upload/image +``` +Upload an image to use in workflows. + +#### View Image +``` +GET /view?filename=image.png&type=output +``` +Returns an image file from the specified location. + +## WebSocket API + +ComfyUI provides real-time updates via WebSocket connection at `/ws`. + +### Connection + +Connect to the WebSocket endpoint: +```javascript +const socket = new WebSocket('ws://localhost:8188/ws'); +``` + +### Message Types + +The WebSocket API sends messages with the following types: + +#### Status Update +```json +{ + "type": "status", + "data": { + "status": { + "exec_info": { + "queue_remaining": 0 + } + }, + "sid": "session_id" + } +} +``` + +#### Execution Started +```json +{ + "type": "execution_start", + "data": { + "prompt_id": "uuid" + } +} +``` + +#### Executing Node +```json +{ + "type": "executing", + "data": { + "node": "node_id", + "prompt_id": "uuid" + } +} +``` + +#### Progress Update +```json +{ + "type": "progress", + "data": { + "value": 1, + "max": 100, + "prompt_id": "uuid", + "node": "node_id" + } +} +``` + +#### Execution Complete +```json +{ + "type": "executed", + "data": { + "node": "node_id", + "output": { + "images": [ + { + "filename": "image.png", + "subfolder": "outputs", + "type": "output" + } + ] + }, + "prompt_id": "uuid" + } +} +``` + +#### Execution Error +```json +{ + "type": "execution_error", + "data": { + "prompt_id": "uuid", + "node_id": "node_id", + "exception_message": "Error message", + "exception_type": "Exception type", + "traceback": ["Traceback lines"] + } +} +``` + +## Python SDK + +ComfyUI provides a Python SDK for easier integration with Python applications. + +### Installation + +```bash +uv pip install comfyui-client +``` + +### Basic Usage + +```python +from comfyui_client import ComfyUIClient + +# Initialize client +client = ComfyUIClient(host="localhost", port=8188) + +# Load a workflow from file +workflow = client.load_workflow("my_workflow.json") + +# Execute workflow +result = client.execute_workflow(workflow) + +# Get generated images +images = client.get_images(result) + +# Save images +for i, img in enumerate(images): + img.save(f"result_{i}.png") +``` + +## Examples + +### Execute a Simple Workflow with cURL + +```bash +curl -X POST http://localhost:8188/prompt -H "Content-Type: application/json" -d @- << 'EOF' +{ + "prompt": { + "3": { + "inputs": { + "seed": 1234, + "steps": 20, + "cfg": 7, + "sampler_name": "euler_ancestral", + "scheduler": "normal", + "denoise": 1, + "model": ["4", 0], + "positive": ["6", 0], + "negative": ["7", 0], + "latent_image": ["5", 0] + }, + "class_type": "KSampler" + }, + "4": { + "inputs": { + "ckpt_name": "dreamshaper_8.safetensors" + }, + "class_type": "CheckpointLoaderSimple" + }, + "5": { + "inputs": { + "width": 512, + "height": 512, + "batch_size": 1 + }, + "class_type": "EmptyLatentImage" + }, + "6": { + "inputs": { + "text": "beautiful landscape, mountains, lake, sunset, detailed, realistic", + "clip": ["4", 1] + }, + "class_type": "CLIPTextEncode" + }, + "7": { + "inputs": { + "text": "blurry, bad quality, low resolution, ugly", + "clip": ["4", 1] + }, + "class_type": "CLIPTextEncode" + }, + "8": { + "inputs": { + "samples": ["3", 0], + "vae": ["4", 2] + }, + "class_type": "VAEDecode" + }, + "9": { + "inputs": { + "filename_prefix": "output", + "images": ["8", 0] + }, + "class_type": "SaveImage" + } + } +} +EOF +``` + +### JavaScript WebSocket Example + +```javascript +const socket = new WebSocket('ws://localhost:8188/ws'); + +socket.onopen = () => { + console.log('Connected to ComfyUI'); +}; + +socket.onmessage = (event) => { + const message = JSON.parse(event.data); + + switch (message.type) { + case 'status': + console.log('Status update:', message.data); + break; + case 'progress': + console.log(`Progress: ${message.data.value}/${message.data.max}`); + break; + case 'executed': + console.log('Node executed:', message.data); + if (message.data.output && message.data.output.images) { + const imagePath = message.data.output.images[0].filename; + console.log('Image generated:', imagePath); + } + break; + case 'execution_error': + console.error('Error:', message.data.exception_message); + break; + } +}; + +// Execute a workflow +fetch('/prompt', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ prompt: workflow }) +}); +``` + +## Best Practices + +### Performance + +- Use batching for multiple related generations +- Avoid polling, use WebSocket for real-time updates +- Reuse model loading nodes across executions + +### Error Handling + +- Always check for and handle error responses +- Implement retries with backoff for transient errors +- Monitor WebSocket for execution_error messages + +### Security + +- Validate all inputs before sending to the API +- Use TLS when exposing ComfyUI outside your network +- Consider implementing authentication for public instances + +### Resource Management + +- Monitor system resources via /system_stats endpoint +- Implement server-side queue limits for multi-user setups +- Use the /free endpoint to release memory when needed \ No newline at end of file From 5e9da4d2ca81679a1af33bd0d7e1b973dff690a5 Mon Sep 17 00:00:00 2001 From: Mister K <678459+kairin@users.noreply.github.com> Date: Fri, 2 May 2025 23:59:21 +0800 Subject: [PATCH 11/11] docs: add comprehensive guide for creating custom nodes in ComfyUI --- docs/custom-nodes.md | 347 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 docs/custom-nodes.md diff --git a/docs/custom-nodes.md b/docs/custom-nodes.md new file mode 100644 index 000000000..fe8774d8e --- /dev/null +++ b/docs/custom-nodes.md @@ -0,0 +1,347 @@ +# Custom Nodes Guide + +This document provides detailed information for developers who want to create custom nodes for ComfyUI. + +## Table of Contents +- [Introduction](#introduction) +- [Setting Up the Development Environment](#setting-up-the-development-environment) +- [Custom Node Structure](#custom-node-structure) +- [Creating Your First Node](#creating-your-first-node) +- [Node Inputs and Outputs](#node-inputs-and-outputs) +- [Advanced Node Development](#advanced-node-development) +- [Distributing Custom Nodes](#distributing-custom-nodes) +- [Best Practices](#best-practices) + +## Introduction + +ComfyUI's power comes from its extensibility through custom nodes. Custom nodes allow you to: + +- Add new functionality not available in the core application +- Optimize existing workflows +- Create specialized interfaces for specific tasks +- Integrate with external tools and services + +This guide will walk you through creating, testing, and distributing custom nodes. + +## Setting Up the Development Environment + +### Prerequisites + +- Python 3.9+ (3.11 recommended) +- ComfyUI installed (source installation recommended for development) +- Basic knowledge of Python +- Understanding of ComfyUI's node system + +### Development Environment Setup + +1. Install ComfyUI from source: + ```bash + git clone https://github.com/comfyanonymous/ComfyUI.git + cd ComfyUI + + # Set up development environment + uv venv .venv + source .venv/bin/activate # Linux/macOS + # or + .venv\Scripts\activate # Windows + + # Install dependencies + uv pip install -e ".[dev]" + ``` + +2. Create a custom nodes directory: + ```bash + mkdir -p custom_nodes/my_custom_node + cd custom_nodes/my_custom_node + ``` + +## Custom Node Structure + +A typical custom node package has the following structure: + +``` +my_custom_node/ +โ”œโ”€โ”€ __init__.py # Entry point for your node +โ”œโ”€โ”€ nodes.py # Node implementation +โ”œโ”€โ”€ requirements.txt # Dependencies +โ”œโ”€โ”€ README.md # Documentation +โ””โ”€โ”€ web/ # [Optional] Frontend components + โ”œโ”€โ”€ js/ + โ”‚ โ””โ”€โ”€ my_node.js # Custom UI components + โ””โ”€โ”€ style.css # Custom styling +``` + +## Creating Your First Node + +### Basic Node Template + +Create a file called `nodes.py` with the following content: + +```python +# nodes.py +import torch +import numpy as np +from PIL import Image + +class MyCustomNode: + """ + A simple custom node that applies a filter to an image. + """ + + # Define the input and output types for the node + @classmethod + def INPUT_TYPES(cls): + return { + "required": { + "image": ("IMAGE",), + "intensity": ("FLOAT", { + "default": 1.0, + "min": 0.0, + "max": 2.0, + "step": 0.01 + }), + }, + } + + # Define the return types + RETURN_TYPES = ("IMAGE",) + # Optional: Define output names (defaults to return types) + RETURN_NAMES = ("filtered_image",) + # Define the node category for UI organization + CATEGORY = "image/filters" + # Optional: Add a description + DESCRIPTION = "Applies a custom filter to the input image" + + def __init__(self): + pass + + def execute(self, image, intensity): + # Convert from tensor format to numpy for processing + # Assuming image is [B, H, W, C] format + img_np = image.numpy() + + # Apply a simple brightness adjustment as an example + adjusted = np.clip(img_np * intensity, 0, 1) + + # Convert back to tensor + result = torch.from_numpy(adjusted) + + return (result,) +``` + +### Register Your Node + +Create an `__init__.py` file to register your node: + +```python +# __init__.py +from .nodes import MyCustomNode + +NODE_CLASS_MAPPINGS = { + "MyCustomNode": MyCustomNode +} + +NODE_DISPLAY_NAME_MAPPINGS = { + "MyCustomNode": "My Custom Filter" +} +``` + +## Node Inputs and Outputs + +### Input Types + +ComfyUI supports several input types: + +- `INT`: Integer values +- `FLOAT`: Floating point values +- `STRING`: Text strings +- `BOOLEAN`: True/False values +- `IMAGE`: Image data +- Custom enum types: A list of string options + +### Input Configuration + +For numeric inputs, you can provide additional configuration: + +```python +"parameter_name": ("FLOAT", { + "default": 1.0, + "min": 0.0, + "max": 10.0, + "step": 0.1, + "display": "slider" # or "number" for a numeric input field +}) +``` + +For dropdown selectors: + +```python +"mode": (["option1", "option2", "option3"],) +``` + +### Output Types + +Common output types include: + +- `IMAGE`: Processed image data +- `MASK`: Image mask data +- `LATENT`: Latent space representation +- `CONDITIONING`: Conditioning data for samplers +- `MODEL`: Model data + +### Multi-Output Nodes + +For nodes with multiple outputs: + +```python +RETURN_TYPES = ("IMAGE", "MASK") +RETURN_NAMES = ("output_image", "image_mask") +``` + +## Advanced Node Development + +### Handling Batches of Images + +To process batches efficiently: + +```python +def execute(self, image, intensity): + # image has shape [B, H, W, C] + batch_size = image.shape[0] + result = [] + + for i in range(batch_size): + # Process each image in the batch + img = image[i] + # Apply processing + processed = self.process_single_image(img, intensity) + result.append(processed) + + # Stack results back into a batch + return (torch.stack(result),) +``` + +### Integrating External Libraries + +For nodes that use external libraries: + +1. Add requirements to `requirements.txt`: + ``` + opencv-python>=4.5.0 + scikit-image>=0.19.0 + ``` + +2. Import and use in your node: + ```python + import cv2 + from skimage import filters + + class ImageProcessingNode: + # ... + def execute(self, image, params): + # Convert to format for OpenCV + img_np = (image.numpy() * 255).astype(np.uint8) + # Process with CV2 + processed = cv2.someFunction(img_np, params) + # Convert back + return (torch.from_numpy(processed / 255.0),) + ``` + +### Custom UI Components + +For advanced UI elements, create a JavaScript file in `web/js/`: + +```javascript +// web/js/my_component.js +import { app } from "../../scripts/app.js"; + +app.registerExtension({ + name: "MyCustomComponent", + async setup(app) { + // Register a custom widget + app.registerNodeDef("MyCustomNode", { + color: "#5588AA", + uiFields: { + "customParameter": (node, inputName) => { + // Create custom UI element + const widget = document.createElement("div"); + widget.innerHTML = `
...
`; + return { element: widget }; + } + } + }); + } +}); +``` + +## Distributing Custom Nodes + +### Packaging + +1. Create a `README.md` with installation and usage instructions +2. Include a `requirements.txt` with dependencies +3. Add example workflows in your documentation +4. Include screenshots of the node in action + +### Installation Instructions + +Provide clear installation instructions: + +```markdown +## Installation + +1. Navigate to your ComfyUI custom_nodes directory +2. Clone this repository: + ``` + git clone https://github.com/username/my-custom-node.git + ``` +3. Install requirements: + ``` + cd my-custom-node + pip install -r requirements.txt + ``` +4. Restart ComfyUI +``` + +### Publishing + +1. Publish your code to GitHub +2. Add your node to the [ComfyUI Custom Nodes List](https://github.com/comfyanonymous/ComfyUI-Custom-Nodes) +3. Share in the ComfyUI Discord community + +## Best Practices + +### Performance + +- Optimize tensor operations for speed +- Use batch processing where possible +- Consider adding a "preview" mode for complex operations +- Clean up resources in `__del__` if needed + +### Compatibility + +- Test with different ComfyUI versions +- Document minimum requirements +- Provide fallbacks for optional dependencies +- Handle different image formats and dimensions + +### User Experience + +- Use clear, descriptive names for nodes and parameters +- Add tooltips with `DESCRIPTION` and input descriptions +- Include examples in your documentation +- Add visual feedback for long-running operations + +### Error Handling + +- Validate inputs before processing +- Provide clear error messages +- Handle edge cases gracefully +- Add debug logging for troubleshooting + +### Version Management + +- Use semantic versioning +- Keep a changelog +- Test thoroughly before releasing updates +- Document breaking changes \ No newline at end of file