Custom nodes are not just a feature of ComfyUI—they form its foundation. Today, the ComfyUI team shares a vision for Nodes v3, an ambitious initiative designed to transform how custom nodes are developed, maintained, and integrated. This project remains a work in progress, and feedback from node authors is highly encouraged—what works well, what needs improvement, and all perspectives in between.

Key Challenges Being Addressed

🔹 Stability
Currently, even minor updates to ComfyUI can disrupt custom nodes due to the absence of a clear separation between internal and public APIs. Nodes v3 introduces a stable public API with guarantees for backward compatibility.

🔹 Dependency Conflicts
Conflicting Python dependencies between node packs can render a ComfyUI installation unusable. The proposed solution involves process isolation to minimize such risks.

🔹 Dynamic I/O & Widgets
While dynamic inputs/outputs and custom widgets are possible today, their implementation remains fragile. Nodes v3 aims to formalize these features with first-class support and a more intuitive schema.

🔹 Model Management
Managing local models has become increasingly cumbersome. Plans are underway to streamline this process through automated detection and better storage organization.

🔹 Future-Proofing
Nodes v3 lays the groundwork for advanced capabilities, including:

• Distributed workflow execution

• Parallel node processing

• And other enhancements

The Proposed Solution

📌 Public API
A documented, versioned API will safeguard nodes against breaking changes while allowing ComfyUI to evolve.

📌 Dependency Isolation
Node packs utilizing the public API may operate within separate Python processes, significantly reducing the likelihood of conflicts.

📌 Modern Schema
The new design replaces opaque dictionaries with an explicit, object-oriented approach, improving readability and flexibility.

📌 Async Execution
The API incorporates async/await to enable parallel and distributed execution without disrupting existing workflows.

Why "v3"?

This initiative builds upon two prior efforts:

• v1: The original (and still predominant) schema

• v2: A partial frontend restructuring
  Nodes v3 represents a comprehensive, full-stack reimagining.

Community Involvement

Node developers are invited to participate in the discussion:

• All users: ComfyUI Discord

• Registry members: Private #exclusive-custom-node-devs channel

Technical Deep Dive: Node Schema

Current Implementation (v1)
The V1 Test Node is written with the current schema:（Python）

# Current (v1) Example
class TestNode:
    @classmethod
    def INPUT_TYPES(cls):
        return {"required": {"image": ("IMAGE",)}}

    RETURN_TYPES = ("IMAGE",)
    FUNCTION = "execute"
    # ...6 more definitions

Proposed v3 Schema
Here is the proposed v3 schema equivalent (subject to change at any time during development):（Python）

# Proposed (v3) Example
class TestNode:
    @classmethod
    def DEFINE_SCHEMA(cls):
        return Schema(
            inputs=[ImageInput("image")],
            outputs=[ImageOutput("processed_image")]
        )

Key improvements include:

• Stateless design: Ensures compatibility across isolated processes or machines

• Type safety: Built-in validation and hints for better reliability

• Dynamic I/O: Native support for runtime adjustments

API Versioning Strategy

Stable API versions ensure long-term compatibility: （Python）

from comfy_api.v0_0_3 import ComfyAPI  # Pinned to a stable version  
api = ComfyAPI()  
await api.set_progress(0.5)  # Async-ready