🚀 UmeAiRT's ComfyUI Auto-Installer

Cross-platform Python CLI to fully automate the installation, update, and configuration of ComfyUI. One-click setup with GPU optimizations, curated custom nodes, and VRAM-aware model downloads.

✨ Features

• One-Click Install — Double-click Install.bat (Windows) or run Install.sh (Linux/macOS)
• Isolated Core — The installer runs in its own dedicated, safe virtual environment (.installer_venv).
• Cross-Platform Compatibility:
  • Windows: Full support for NVIDIA (CUDA), AMD (ROCm), and CPU-only fallbacks.
  • Linux: Full support for NVIDIA (CUDA), AMD (ROCm), and CPU-only fallbacks.
  • macOS: Full support leveraging Apple Silicon (MPS).
• Flexible Installations: Supports both uv Virtual Environments (venv) and Git-tracked conda/venv integration.
• GPU Optimizations — Installs Triton, SageAttention (Unified ABI3 for v2 + Native RTX 50XX Blackwell Support for v3), and xformers with version compatibility
• 34 Curated Custom Nodes — Additive manifest system — never removes user-installed nodes
• Model Catalog v3 — 7 model families (FLUX, Z-IMAGE, WAN 2.1, WAN 2.2, HiDream, QWEN, LTX-2) with VRAM-based recommendations and SHA-256 integrity
• Multi-Source Downloads — aria2c accelerated, with HuggingFace + ModelScope fallback
• Junction Architecture — User data (models, outputs) persists independently from ComfyUI updates
• Smart Update — One command to update ComfyUI core, all bundled nodes, and Python dependencies
• Model Security Scanner — Detects malicious pickle code in .ckpt/.pt model files using picklescan
• Cross-Platform Launchers — Generated .bat/.sh scripts (Performance, LowVRAM, Manager TUI)
• Verbose Mode — Clean output by default, detailed logging with -v flag

📋 Prerequisites

• Git
• GPU: NVIDIA (CUDA 12.x+), AMD (Radeon RX 6000+), or Apple Silicon (M1+)
• Internet connection
• [Optional] C++ Compiler: Windows users might need Visual Studio Build Tools (C++ workload) if installing custom nodes that require source compilation (e.g., insightface). Linux/macOS users usually have gcc/clang installed by default.

Note: Python 3.13 is auto-installed via uv if not present. No manual Python setup required.

🏁 Quick Start

Option A: One-Liner (Recommended)

Windows (PowerShell):

irm https://get.umeai.art/comfyui.ps1 | iex

Linux / macOS:

curl -fsSL https://get.umeai.art/comfyui.sh | sh

Only requires Git — everything else (Python, uv, dependencies) is handled automatically.

Option B: Manual Download

1. Download or clone this repository
2. Double-click Install.bat (Windows) or run ./Install.sh (Linux/macOS)
3. Follow the on-screen prompts (install type, model packs)
4. When done, double-click UmeAiRT-Start-ComfyUI.bat to launch!

Option C: CLI (Advanced)

# Install the CLI tool
pip install -e .

# Run the installer
umeairt-comfyui-installer install --path /path/to/install --type venv

# With verbose output
umeairt-comfyui-installer install --path /path/to/install -v

Option D: Docker Container

Requires Docker and an NVIDIA GPU.

docker run --gpus all -p 8188:8188 -v comfyui-data:/data -e NODE_TIER=full registry.gitlab.com/umeairt-studio/comfyui-auto_installer-python:latest

Open http://localhost:8188 — done! ✅

All your data (models, nodes, outputs) is stored in the comfyui-data volume and persists between restarts. To use a local folder instead: replace comfyui-data:/data with ./comfyui_data:/data.

Available image variants:

Cloud variant (with JupyterLab for RunPod / remote):

docker run --gpus all --name comfyui -p 8188:8188 -p 8888:8888 -v comfyui-data:/data -e JUPYTER_ENABLE=true -e NODE_TIER=umeairt registry.gitlab.com/umeairt-studio/comfyui-auto_installer-python:latest-cloud

Tip: Use -e NODE_TIER=minimal, umeairt, or full (default) to control which custom nodes are installed on boot. The lite variants are ideal for RunPod where fast image pulls matter — PyTorch installs once on first boot and is cached in the persistent volume.

🔄 Migrating from the PowerShell Version

If you're currently using the PowerShell version (ComfyUI-Auto_installer-PS), you can migrate to this Python version with a single command. All your data (models, outputs, custom nodes) will be preserved.

irm https://get.umeai.art/migrate.ps1 | iex

The script will:

• Auto-detect your PowerShell installation
• Clean up PS-specific files (scripts, old venv, old launchers)
• Bootstrap the new Python environment (uv + venv)
• Reinstall all Python dependencies for every custom node (including user-installed)
• Generate new launcher scripts

⚠️ This operation is irreversible. It is strongly recommended to back up your installation folder before proceeding. The script will suggest a backup command before asking for confirmation.

📂 Post-Installation

Four launcher scripts are generated in your install directory:

🩺 Troubleshooting

Expand-Archive ... the module could not be loaded / the system cannot find the drive specified

Both messages come from the same cause: PowerShell inherited a working directory that no longer exists — a disconnected network drive, a deleted folder, or a non-filesystem location. Module autoloading then fails, and Expand-Archive becomes unavailable.

Immediate workaround on any version:

cd /d %USERPROFILE%

then run the installer again from there.

Since v6.0.1 the installer handles this on its own: extraction falls back through System32\tar.exe → .NET → Expand-Archive, and it now aborts with an explicit message if uv.exe was not actually produced — instead of continuing and failing later on an unrelated step.

SageAttention: a node crashes with Fatal Python error: Aborted

If a Patch Sage Attention node (KJNodes and similar) crashes or renders black images, bypass it. Our launchers already enable SageAttention natively via --use-sage-attention, so the node is redundant — and the crash is an upstream bug in the node's wrapper, not in SageAttention itself (KJNodes #670).

Alternative without any installation: ComfyUI ≥ v0.32.0 ships a ModelAttentionBackend node that selects the attention implementation per model, with a built-in backend at roughly the same performance as SageAttention. It falls back to PyTorch attention when unavailable.

🛠️ CLI Commands

umeairt-comfyui-installer                    # TUI manager (launch, update, download, settings)
umeairt-comfyui-installer install            # Full installation
umeairt-comfyui-installer install --reinstall # Clean reinstall (preserves models/output)
umeairt-comfyui-installer update             # Update ComfyUI + nodes + deps
umeairt-comfyui-installer download-models    # Interactive model downloads
umeairt-comfyui-installer scan-models        # Scan models for malicious pickle code
umeairt-comfyui-installer info               # Display system info (GPU, Python, tools)
umeairt-comfyui-installer version            # Show version

All commands support --path (install directory) and --verbose flags.

📁 Architecture

Project Structure

ComfyUI-Auto_installer/
├── umeairt_installer/
│   ├── cli.py                # Typer CLI entry point
│   ├── config.py             # Pydantic config models
│   ├── installer/            # Install, update, nodes, finalize
│   │   ├── templates/        # .bat/.sh launcher templates
│   │   └── ...
│   ├── downloader/           # Model download engine (manifest v3)
│   ├── platform/             # OS abstraction (Windows/Linux/macOS)
│   └── utils/                # Logging, commands, packaging, GPU detection
├── scripts/                  # Config files (dependencies.json, custom_nodes.json)
├── tests/                    # 438 tests (unit + integration)
├── Install.bat / Install.sh  # Bootstrap entry points
└── pyproject.toml            # Project metadata (hatchling)

Install Directory Layout

The installer uses a junction-based architecture to separate user data from ComfyUI core:

install_path/
├── scripts/venv/            # Python virtual environment (venv or conda)
├── ComfyUI/                 # Git repo (can be wiped for updates)
│   ├── models/ → ../models  # ← junction (symlink)
│   ├── output/ → ../output  # ← junction
│   └── main.py
├── models/                  # ← User data (persists)
├── output/                  # ← User data (persists)
├── logs/                    # Install and update logs
├── scripts/                 # Venv, config files, install metadata
├── UmeAiRT-Start-ComfyUI.bat
├── UmeAiRT-Start-ComfyUI_LowVRAM.bat
└── UmeAiRT-Manager.bat

Model Catalog (v3)

Models are defined in model_manifest.json, fetched from the Assets repository at install/update time:

Each bundle offers multiple quantization variants (fp16, fp8, GGUF Q3→Q8) with VRAM recommendations (★ markers) and SHA-256 integrity checks. Downloads are accelerated via aria2c with HuggingFace + ModelScope fallback.

🧑‍💻 Contributing

Contributions are welcome! See AGENTS.md for development guidelines and docs/codemaps/ for architecture diagrams.

# Setup development environment
uv sync --dev

# Run tests
uv run pytest tests/ -q

# Lint
uv run ruff check umeairt_installer/ tests/

📜 Third-Party Code & Attribution

🔒 Security

• No external script execution — all installation logic is internalized
• Secure subprocess calls — no shell=True, explicit argument lists
• HTTPS only — all download URLs validated
• Automated audits — CI runs Bandit + pip-audit on every push
• Pickle model scanner — Detects malicious code in .ckpt/.pt files via picklescan (auto-runs during updates)
• Zip slip prevention — Archive extraction validates all paths stay within the target directory
• SHA-256 integrity — Post-download checksum verification for all model files

For details, see SECURITY.md.

📝 License

MIT License — see LICENSE file.

❤️ Credits

Developed by UmeAiRT. Thanks to Comfyanonymous for creating ComfyUI and to all custom node authors.