​
Specifications

The pyproject.toml file contains two main sections for ComfyUI custom nodes: [project] and [tool.comfy]. Below are the specifications for each section.

​
[project] Section

​
name (required)

The node id uniquely identifies the custom node and will be used in URLs from the registry. Users can install the node by referencing this name:

comfy node install <node-id>

Requirements:

  • Must be less than 100 characters
  • Can only contain alphanumeric characters, hyphens, underscores, and periods
  • Cannot have consecutive special characters
  • Cannot start with a number or special character
  • Case-insensitive comparison

Best Practices:

  • Use a short, descriptive name
  • Don’t include “ComfyUI” in the name
  • Make it memorable and easy to type

Examples:

name = "image-processor"      # ✅ Good: Simple and clear
name = "super-resolution"     # ✅ Good: Describes functionality
name = "ComfyUI-enhancer"    # ❌ Bad: Includes ComfyUI
name = "123-tool"            # ❌ Bad: Starts with number

See the official python documentation for more details.

​
version (required)

Uses semantic versioning with a three-digit version number X.Y.Z:

  • X (MAJOR): Breaking changes
  • Y (MINOR): New features (backwards compatible)
  • Z (PATCH): Bug fixes

Examples:

version = "1.0.0"    # Initial release
version = "1.1.0"    # Added new features
version = "1.1.1"    # Bug fix
version = "2.0.0"    # Breaking changes

​
license (optional)

Specifies the license for your custom node. Can be specified in two ways:

  1. File Reference:
license = { file = "LICENSE" }     # ✅ Points to LICENSE file
license = { file = "LICENSE.txt" } # ✅ Points to LICENSE.txt
license = "LICENSE"                # ❌ Incorrect format
  1. License Name:
license = { text = "MIT License" }  # ✅ Correct format
license = { text = "Apache-2.0" }   # ✅ Correct format
license = "MIT LICENSE"             # ❌ Incorrect format

Common licenses: MIT, GPL, Apache

A brief description of what your custom node does.

description = "A super resolution node for enhancing image quality"

Links to related resources:

[project.urls]
Repository = "https://github.com/username/repository"
Documentation = "https://github.com/username/repository/wiki"
"Bug Tracker" = "https://github.com/username/repository/issues"

Specifies the Python versions that your node supports:

requires-python = ">=3.8"        # Python 3.8 or higher
requires-python = ">=3.8,<3.11"  # Python 3.8 up to (but not including) 3.11

Use classifiers to specify operating system compatibility and other metadata. The most relevant classifiers for operating systems are:

[project]
classifiers = [
    # For OS-independent nodes (works on all operating systems)
    "Operating System :: OS Independent",

    # OR for OS-specific nodes, specify the supported systems:
    "Operating System :: Microsoft :: Windows",  # Windows specific
    "Operating System :: POSIX :: Linux",  # Linux specific
    "Operating System :: MacOS",  # macOS specific
    
    # You can be more specific if needed
    "Operating System :: Microsoft :: Windows :: Windows 10",
    "Operating System :: POSIX :: Linux :: Ubuntu",
    "Operating System :: MacOS :: MacOS X",
]

Common Combinations:

# For nodes that work on all operating systems
classifiers = [
    "Operating System :: OS Independent",
]

# For Windows-only nodes
classifiers = [
    "Operating System :: Microsoft :: Windows",
    "Operating System :: Microsoft :: Windows :: Windows 10",
]

# For specific OS combinations (e.g., Linux and macOS only)
classifiers = [
    "Operating System :: POSIX :: Linux",
    "Operating System :: MacOS",
]

See the full list of valid classifiers on PyPI.

​
[tool.comfy] Section

​
PublisherId (required)

Your unique publisher identifier, typically matching your GitHub username.

Examples:

PublisherId = "john-doe"        # ✅ Matches GitHub username
PublisherId = "image-wizard"    # ✅ Unique identifier

​
DisplayName (optional)

A user-friendly name for your custom node.

DisplayName = "Super Resolution Node"

​
Icon (optional)

URL to your custom node’s icon.

Requirements:

  • File types: SVG, PNG, JPG, or GIF
  • Maximum resolution: 800px × 400px
Icon = "https://raw.githubusercontent.com/username/repo/main/icon.png"

​
Complete Example

[project]
name = "super-resolution-node"
version = "1.0.0"
description = "Enhance image quality using advanced super resolution techniques"
license = { file = "LICENSE" }
requires-python = ">=3.8"
classifiers = [
    "Operating System :: OS Independent"  # Works on all operating systems
]
dynamic = ["dependencies"]

[tool.setuptools.dynamic]
dependencies = {file = ["requirements.txt"]}

[project.urls]
Repository = "https://github.com/username/super-resolution-node"
Documentation = "https://github.com/username/super-resolution-node/wiki"
"Bug Tracker" = "https://github.com/username/super-resolution-node/issues"

[tool.comfy]
PublisherId = "image-wizard"
DisplayName = "Super Resolution Node"
Icon = "https://raw.githubusercontent.com/username/super-resolution-node/main/icon.png"