Dependency Conflicts

Dependency conflicts are the #1 hidden killer of ComfyUI environments. A plugin installs a package, that package downgrades PyTorch, and suddenly nothing works. This guide teaches you how to diagnose, fix, and prevent these issues.

Understanding the Problem

ComfyUI plugins are independent Git repos, each with their own requirements.txt. When you install 20+ plugins, their dependency declarations often conflict:

• Plugin A wants numpy>=2.0
• Plugin B wants numpy<2.0
• Plugin C wants pillow>=10.3
• Plugin D wants pillow<10.0

These are real examples from production ComfyUI environments.

Step 1: Diagnose

Check for Import Failures

Look at the ComfyUI startup log for lines containing IMPORT FAILED:

IMPORT FAILED: ComfyUI-TeaCache
  AttributeError: module 'comfy.model_sampling' has no attribute '_precompute_freqs_cis'

This tells you which plugin failed and why. See the Troubleshooting Decision Tree for a systematic way to classify these errors.

Check with pip

pip check

This shows all broken dependency relationships. Example output:

colour-science 0.4.6 requires numpy>=2, but you have numpy 1.26.4
opencv-python 4.10.0 requires numpy>=2, but you have numpy 1.26.4

Check Manager's Failure Info

If ComfyUI is running, visit:

http://127.0.0.1:8188/v2/customnode/import_fail_info_bulk

This returns a JSON list of which plugins failed to import and why.

Step 2: Classify the Problem

Not every pip check warning is a real problem. Classify each issue:

Hard Blockers (Fix Immediately)

These prevent plugins from loading:

• torch version mismatch — wrong CUDA build
• Missing package that a plugin directly imports
• Two plugins requiring non-overlapping versions of the same package

Soft Drift (Monitor, Don't Fix)

These show up in pip check but don't actually break anything:

• A package declares numpy>=2 but works fine with numpy 1.26.4
• An optional sub-dependency has a version mismatch

Rule of thumb: If ComfyUI starts, the plugin loads, and your workflows run — it's soft drift.

Declaration Errors (Work Around)

Sometimes plugin authors make mistakes in their dependency files:

• Typos: libros instead of librosa, requirements-parserx instead of requirements-parser
• Impossible combinations: one file says pillow>=10.3, another file in the same repo says pillow<10.0

Don't fix these by editing the plugin source code. Document the workaround.

Step 3: Fix

Rule 1: Protect Your Core Runtime

These packages must NEVER be accidentally downgraded by a plugin install:

Package	Why It's Critical
torch / torchvision / torchaudio	Core GPU computation. Wrong version = nothing works
numpy	Almost every plugin depends on it
pillow	Image processing foundation
opencv-python	Used by ControlNet, face detection, many workflows
transformers / diffusers / huggingface-hub	Model loading and inference

Before installing any plugin requirements, check if they would change these packages:

pip install -r requirements.txt --dry-run

Rule 2: Use Minimal Fixes

Don't do broad upgrades. Pin specific versions:

# Bad: upgrades everything, may break other plugins
pip install -U transformers

# Good: pin to a known working version
pip install transformers==4.57.6

Rule 3: Use --no-deps for Tricky Packages

Some packages try to install their own version of PyTorch:

# This will try to install torch, potentially breaking your CUDA build
pip install nunchaku

# This installs only the package itself
pip install nunchaku --no-deps

Rule 4: Use Pre-built Wheels

For packages that need compilation (like nunchaku, insightface, dlib), don't try to build from source on Windows. Find a pre-built wheel:

# Direct wheel URL for exact Python + PyTorch + CUDA combo
pip install https://github.com/nunchaku-ai/nunchaku/releases/download/v1.0.1/nunchaku-1.0.1+torch2.8-cp312-cp312-win_amd64.whl

Rule 5: Don't Install What You Don't Need

If a plugin declares an optional dependency that your workflows don't use:

• Don't install it — it may destabilize your environment
• Example: facenet-pytorch is optional for PuLID. If your workflows don't use the FaceNet path, skipping it is the right choice
• Example: dlib and tb-nightly are often declared but rarely needed by actual workflows

Common Conflict Recipes

BizyAir Pollutes starlette

Problem: BizyAir auto-updates its dependencies on startup, changing starlette version.

Fix:

pip install starlette==0.37.2 sse-starlette==2.1.3

Also prevent future auto-updates by setting this environment variable before launching:

BIZYAIR_SKIP_UPDATE=1

HuggingFace Stack Drift

Problem: diffusers, transformers, huggingface-hub, and accelerate must stay in a compatible set.

Fix: Install them together:

pip install diffusers>=0.35,<0.36 transformers>=4.54,<5 huggingface-hub>=0.30 accelerate>=1.10

numpy 2.x vs 1.x War

Problem: New packages want numpy>=2, but FluxTrainer and some video plugins need numpy 1.26.x.

Fix: Keep numpy==1.26.4 and accept the pip check warnings as soft drift. Everything still works.

xformers Breaks torch

Problem: Installing xformers with the wrong version pulls in a different torch build.

Fix: Only install xformers if you have a verified compatible combination:

Python	torch	xformers	Status
3.12	2.8.0+cu129	?	No verified combo yet — skip
3.11	2.4.0+cu121	0.0.27.post2	Verified

If no compatible version exists for your setup, use --use-pytorch-cross-attention instead.

Recovery: When Your Environment Is Broken

If a bad install has already corrupted your core packages:

Option 1: Reinstall Core Packages

pip install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128
pip install numpy==1.26.4 pillow==12.1.1

Option 2: Start Fresh (Nuclear Option)

If the environment is too damaged to recover:

1. Delete the virtual environment / python_embeded folder
2. Re-extract from the Portable Package or re-run the Desktop installer
3. Reinstall plugins one at a time, checking after each (see Custom Nodes)

Related Guides

• Plugin Management — Advanced node mapping, batch management, and Git LFS issues
• Workflow Environment Setup — Full 7-stage SOP including dependency resolution as Stage 5
• Troubleshooting Decision Tree — Systematic error diagnosis
• Common Issues — Quick fixes for the most frequent problems

Need Help?

Dependency conflicts in multi-plugin ComfyUI environments are our specialty. If you're stuck in dependency hell, book a remote fix session — we'll untangle it live.