How to Create ComfyUI Nodes with SEARCH_ALIASES for Better Discoverability

Add a SEARCH_ALIASES class attribute to legacy nodes or pass search_aliases to io.Schema in modern nodes to make them searchable by alternative names in the ComfyUI node palette.

Finding the right node in a crowded ComfyUI workflow can be frustrating for users. The Comfy-Org/ComfyUI repository provides a SEARCH_ALIASES mechanism that allows node developers to expose alternative searchable terms, ensuring users can locate specific functionality through the web interface search bar and the /object_info API endpoint.

Two Methods to Define SEARCH_ALIASES

ComfyUI supports two distinct patterns for defining search aliases depending on which node base class you inherit from. Both methods ultimately populate the same index consumed by the frontend.

Legacy Class Attribute Approach

For nodes inheriting from ComfyNodeABC (the classic base class), define a class-level list named SEARCH_ALIASES. The server extracts this attribute in server.py at line 691:

# server.py – line 691

info['search_aliases'] = getattr(obj_class, 'SEARCH_ALIASES', [])

Many built-in nodes in nodes.py (lines 74-159) use this pattern. For example, CLIPTextEncode and ConditioningCombine expose aliases that help users find these nodes when searching for related concepts.

Modern Schema-Based Approach

For nodes using the newer io.ComfyNode base class, pass the search_aliases parameter when constructing the io.Schema. This approach is demonstrated in comfy_extras/nodes_string.py at line 14:

# comfy_extras/nodes_string.py – line 14

search_aliases=["text concat", "join text", …]

The server automatically checks for this field in the schema definition if the legacy attribute is not present, ensuring backward compatibility while supporting modern node architecture.

Step-by-Step Implementation

Follow these steps to add discoverable aliases to your custom node:

1. Create your node file in the custom_nodes/ directory (e.g., my_custom_node.py).

2. Choose your inheritance pattern:

   • Legacy: Subclass ComfyNodeABC from comfy.comfy_types
   • Modern: Subclass io.ComfyNode from comfy_api.latest

3. Implement the aliases:

   • For legacy nodes, add the class attribute:

     class MyLegacyNode(ComfyNodeABC):
         SEARCH_ALIASES = ["demo", "legacy test", "quick add"]
         
         @classmethod
         def INPUT_TYPES(s) -> InputTypeDict:
             return {
                 "required": {
                     "value": (IO.INT, {"default": 1, "min": 0, "max": 100}),
                 }
             }
         
         RETURN_TYPES = (IO.INT,)
         FUNCTION = "process"
         CATEGORY = "utils/custom"
         
         def process(self, value):
             return (value + 10,)

   • For modern nodes, define within the schema:

     from comfy_api.latest import io
     
     class MyModernNode(io.ComfyNode):
         @classmethod
         def define_schema(cls):
             return io.Schema(
                 node_id="MyModernNode",
                 display_name="My Modern Node",
                 category="utils/custom",
                 search_aliases=["demo", "modern test", "quick compute"],
                 inputs=[
                     io.Float.Input("factor", default=1.0),
                     io.Int.Input("offset", default=0),
                 ],
                 outputs=[
                     io.Float.Output(display_name="result"),
                 ]
             )
     
         @classmethod
         def execute(cls, factor, offset):
             return io.NodeOutput(factor * 2 + offset)

4. Reload the UI or restart ComfyUI. The aliases immediately become searchable in the node palette.

Verifying Aliases via the API

Confirm your implementation by querying the /object_info endpoint. The server includes the alias list in the JSON payload for each node:

curl http://localhost:8188/object_info | jq '.["MyModernNode"].search_aliases'

Expected output:

[
  "demo",
  "modern test",
  "quick compute"
]

This JSON structure feeds directly into the global search index, enabling both the web UI and external tools to surface your node when users type any of the specified aliases.

Summary

• SEARCH_ALIASES improves node discoverability by mapping alternative search terms to your node class.
• Legacy nodes use a class attribute (SEARCH_ALIASES = ["term1", "term2"]) extracted by server.py.
• Modern nodes use the search_aliases parameter in io.Schema as shown in comfy_extras/nodes_string.py.
• The Web UI performs case-insensitive, partial matching against these aliases.
• The /object_info endpoint exposes aliases to external tools and extensions.

Frequently Asked Questions

What is the maximum number of aliases I should define?

Define 3 to 5 concise, distinct terms that cover common synonyms or related concepts. Avoid excessive aliases that dilute search precision. The ComfyUI frontend indexes all provided strings, but cluttered results can overwhelm users.

Can I use SEARCH_ALIASES with any custom node class?

Yes, provided your node is properly registered in the ComfyUI node system. The server in server.py uses getattr(obj_class, 'SEARCH_ALIASES', []), which safely returns an empty list if the attribute is missing. For modern nodes using io.ComfyNode, ensure you import comfy_api.latest and define a valid io.Schema.

Do search aliases affect node execution or only the UI?

Aliases affect only discoverability, not execution logic. They are metadata consumed by the frontend and the /object_info API endpoint. The actual computation in your FUNCTION (legacy) or execute (modern) method remains unchanged regardless of which alias a user searched to find the node.

How do I debug if my aliases are not appearing?

First, verify your node loads without errors in the ComfyUI console. Then query the /object_info endpoint and check the search_aliases field for your specific node_id. If the field is empty or missing, confirm you used the correct attribute name (SEARCH_ALIASES for legacy, search_aliases for schema-based) and that your class inherits from the appropriate base (ComfyNodeABC or io.ComfyNode).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}