comfy-env

Environment management and automatic CUDA wheel resolution/installation for ComfyUI custom nodes.

The Problem(s) and Solution(s)

Problem 1: ComfyUI custom nodes share a single Python environment. This breaks when:

Node A needs torch 2.4, Node B needs torch 2.8
Two packages bundle conflicting native libraries (libomp, CUDA runtimes, cv2)
A node requires a specific Python version (e.g., Blender needs 3.11, pymesh2 needs 3.9)

Solution 1: comfy-env provides process isolation -- nodes that need conflicting dependencies run in their own Python environments as persistent subprocesses, transparent to ComfyUI.

Two config files, two roles:

comfy-env-root.toml (root level): ComfyUI node dependency management plus pack-level settings and env vars. Never touches the Python environment -- PyPI deps stay in requirements.txt.
comfy-env.toml (subdirectories): Each subdirectory with this file gets its own isolated Python environment via pixi, with a separate interpreter, conda packages, pip packages, and pre-built CUDA wheels.

Using conda CANNOT be avoided. We need to be able to use ComfyUI functions and return types within isolated nodes, which means they will need things like av or ffmpeg, and those cannot be installed through PyPI. Pixi is a convenient, fast, Rust-based package manager that speaks both conda-forge AND PyPI in the same pixi.toml, ships a real lockfile (so envs are reproducible across machines), installs entirely per-user with no admin / no system Python pollution, and uses uv under the hood for the PyPI side -- so it's as fast as the fastest thing in the ecosystem.

Problem 2: With the advent of ever more complex and useful Computer Vision ML models, code relies on CUDA packages like flash-attn, nvdiffrast, nunchaku, pytorch3d to work. Every single CUDA compiled wheel is compiled for:

Python ABI (3.10, 3.11, 3.12 etc)
Pytorch version when linking against pytorch, can be from 2.4 to 2.11
CUDA version (12.8, 13.0)
OS (Windows vs Linux)
GPU architectures (8.0 and above)

Solution 2: In order to ensure a smooth use and installation for ComfyUI users, we offer automatic wheel resolution through a cuda index: https://github.com/PozzettiAndrea/cuda-wheels.

Architecture

ComfyUI-MyPack/
+-- comfy-env-root.toml            # System packages + node deps
+-- install.py                     # from comfy_env import install; install()
+-- prestartup_script.py           # from comfy_env import setup_env; setup_env()
+-- __init__.py                    # from comfy_env import register_nodes
`-- nodes/
    +-- main/                      # No config -> imported in main process
    |   `-- __init__.py
    `-- cgal/                      # Has config -> isolated subprocess
        +-- comfy-env.toml
        `-- __init__.py

<workspace>/                       # %LOCALAPPDATA%\Programs\comfy-env  (Windows)
                                   # ~/.ce                              (Unix)
+-- pixi.toml                      # Generated from every discovered comfy-env.toml
`-- .pixi/envs/
    +-- mypack-cgal/               # Env for ComfyUI-MyPack/nodes/cgal/
    |   +-- python                 #   Complete Python interpreter
    |   `-- lib/.../site-packages/ #   + isolated packages
    `-- <plugin>-<subdir>/         # Each isolation config gets its own named env
        `-- ...

Env names are derived as <plugin>-<subdir> (or just <plugin> for root-level configs), with the ComfyUI- prefix stripped and the result lowercased: comfyui-sam3/nodes -> sam3-nodes, comfyui-motioncapture/nodes -> motioncapture-nodes, etc. See get_env_name.

Examples in the wild

ComfyUI-TRELLIS2 -- root-only config (comfy-env-root.toml). No isolation env; uses comfy-env purely for CUDA wheel resolution (flash-attn, sageattention) and to declare ComfyUI-GeometryPack as a node dependency. Runs inside the host ComfyUI process.
ComfyUI-Hunyuan3D-Part -- same pattern; lightest possible use of comfy-env.
ComfyUI-GeometryPack -- full isolation env. nodes/comfy-env.toml declares conda deps from conda-forge + a custom pozzettiandrea channel (CGAL, igl, bpy, pyvista), one CUDA package (cumesh), PyPI deps pinned via custom simple indexes (pyQuadriFlow, pygeogram, pypmp, pymesh2), and per-platform extras (mesalib/libglu/xorg-libsm on Linux, embreex/msvc-runtime on Windows). This is the env that doesn't fit in the host venv.
cookiecutter-comfy-extension -- scaffold for new node packs; ships a minimal comfy-env.toml template and the canonical install.py / prestartup_script.py / __init__.py triplet.

How It Works

Build time (install.py): For each subdirectory with a comfy-env.toml, comfy-env computes its env name (see above), generates a single pixi.toml in the workspace with one [environments.<name>] entry per discovered config, and runs pixi install -e <name> to materialize each environment. Identical env names from different ComfyUI installs share the same materialized env on disk -- env names act as the global identifier.

Workspace location: a single per-user pixi workspace, shared by every ComfyUI install on the machine. On Windows the default is %LOCALAPPDATA%\Programs\comfy-env (sits next to the ComfyUI Desktop install at %LOCALAPPDATA%\Programs\ComfyUI; never needs admin to create). If comfy-env detects an env at the legacy drive-root path C:\ce, it prints a one-line "please reinstall" nudge at startup so users notice the migration.

On Linux/MACOS the default is ~/.ce. Override with the COMFY_ENV_ROOT env var.

Runtime (register_nodes()): Discovers all node subdirectories. Those with a built env at <workspace>/.pixi/envs/<env_name>/ run in persistent subprocess workers using the isolated Python interpreter. Those without a config (or whose env hasn't been materialized yet) are imported normally in the main ComfyUI process. Workers communicate via Unix domain sockets (TCP on Windows) and support bidirectional callbacks for VRAM budget negotiation and progress reporting.

CUDA packages: Listed in [cuda], installed from the PyTorch wheel index or cuda-wheels -- pre-built wheels for nvdiffrast, pytorch3d, gsplat, flash-attn, etc. No CUDA toolkit or C++ compiler needed. The resolver tries the GitHub Pages simple index first, retries transient TCP-reset errors with a real User-Agent (corp proxies / AV products RST Python-urllib), and falls back to the GitHub Releases API on a different routing edge when Pages is unreachable end-to-end.

Startup logging

On every ComfyUI launch, comfy-env's prestartup hook tells you exactly where envs live and whether each one is built:

[comfy-env] Workspace: C:\Users\you\AppData\Local\Programs\comfy-env
[comfy-env] comfyui-motioncapture: 1 isolation env(s):
[comfy-env]   nodes -> C:\Users\you\...\custom_nodes\comfyui-motioncapture\nodes
[comfy-env]     env: C:\Users\you\AppData\Local\Programs\comfy-env\.pixi\envs\motioncapture-nodes  [OK]
[comfy-env] prestartup complete

[MISSING -- run install.py] instead of [OK] means the config was discovered but the pixi env hasn't been materialized; run the node's install.py to build it.

Usage

# install.py
from comfy_env import install
install()

# prestartup_script.py
from comfy_env import setup_env
setup_env()

# __init__.py
from comfy_env import register_nodes
NODE_CLASS_MAPPINGS, NODE_DISPLAY_NAME_MAPPINGS = register_nodes()

pip install comfy-env

Metadata

Release files for comfy-env 0.4.39

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for comfy-env 0.4.39
File	Size	Uploaded
comfy_env-0.4.39.tar.gz	417.2 kB	Sep 8, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for comfy-env 0.4.39
File	Interpreter	ABI	Platform	Reset
comfy_env-0.4.39-py3-none-any.whl 277.3 kB Sep 8, 2026	Python 3	none	any	Details

Total release size: 694.6 kB

Release files / comfy_env-0.4.39.tar.gz

Download URL	comfy_env-0.4.39.tar.gz
Size	417.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`f77b18d25ef1dd61e08b910d54ce061d647b987ab8577f8ba1f50d99cadcb38e`
BLAKE2b-256 checksum How to use checksums	`cf163d675b6223bec69a778ffed04018fba38954dcc2a489f804d288c503e8b5`
Upload date	Sep 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/PozzettiAndrea/comfy-env
Publishing commit: github.com/PozzettiAndrea/comfy-env/tree/5fae056ec58403e31b36a327a28d96216d37c3e3

Workflow

Publishing configuration: github.com/PozzettiAndrea/comfy-env/blob/5fae056ec58403e31b36a327a28d96216d37c3e3/.github/workflows/publish.yml
Publishing logs: github.com/PozzettiAndrea/comfy-env/actions/runs/34198132288/attempts/1

Artifact

Subject: comfy_env-0.4.39.tar.gz
SHA-256 checksum: f77b18d25ef1dd61e08b910d54ce061d647b987ab8577f8ba1f50d99cadcb38e Verifying attestations

Release files / comfy_env-0.4.39-py3-none-any.whl

Download URL	comfy_env-0.4.39-py3-none-any.whl
Size	277.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5fb889f8c7d762be7f11f63606f02fbe34148be9b4373fb64405d97aec0180fa`
BLAKE2b-256 checksum How to use checksums	`d5cac56f5cb47f6910322f5eafb53a56b7fe9491feec541937ca016bd6aee562`
Upload date	Sep 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/PozzettiAndrea/comfy-env
Publishing commit: github.com/PozzettiAndrea/comfy-env/tree/5fae056ec58403e31b36a327a28d96216d37c3e3

Workflow

Publishing configuration: github.com/PozzettiAndrea/comfy-env/blob/5fae056ec58403e31b36a327a28d96216d37c3e3/.github/workflows/publish.yml
Publishing logs: github.com/PozzettiAndrea/comfy-env/actions/runs/34198132288/attempts/1

Artifact

Subject: comfy_env-0.4.39-py3-none-any.whl
SHA-256 checksum: 5fb889f8c7d762be7f11f63606f02fbe34148be9b4373fb64405d97aec0180fa Verifying attestations