How the ComfyUI Custom Node Prestartup Script System Works

ComfyUI executes a prestartup_script.py file from each custom node package before importing any node classes, allowing one-time initialization via importlib while supporting whitelist and disable flags for security.

The custom node prestartup script system in ComfyUI provides extension developers with a hook to run Python code exactly once during application startup. According to the Comfy-Org/ComfyUI source code, this mechanism triggers after path resolution but before the main node loading phase in nodes.py, ensuring that environment setup and global registrations complete successfully before any node classes are instantiated.

How the Prestartup Script System Works

The execution flow is implemented in main.py within the execute_prestartup_script() function (lines 15-63). The system follows a strict six-step discovery and execution process:

1. Directory Discovery – The system calls folder_paths.get_folder_paths("custom_nodes") to retrieve all configured extension directories (typically <base>/custom_nodes).
2. Package Iteration – It iterates over every subfolder, treating each as an individual custom node package.
3. Permission Checks – The system respects disable flags from comfyui_manager and CLI arguments to skip unauthorized packages.
4. File Detection – It searches for a file named exactly prestartup_script.py in the package root.
5. Dynamic Execution – Found scripts are loaded via importlib.util.spec_from_file_location and executed using spec.loader.exec_module.
6. Logging – Execution time and success status are recorded and reported after the phase completes.

Security and Control Mechanisms

The system includes multiple layers of access control defined in comfy/cli_args.py. When the --disable-all-custom-nodes flag is present, the engine skips all prestartup scripts unless the package appears in the --whitelist-custom-nodes list. Additionally, the optional comfyui_manager integration calls prestartup() immediately before the main execution loop, allowing external managers to veto specific packages programmatically.

Error Handling and Isolation

Each script executes in an isolated import context. If a prestartup_script.py raises an exception, the error is caught and logged without terminating the startup sequence. This ensures that a faulty custom node cannot prevent ComfyUI from launching.

Key Source Files and Functions

Understanding the following files is essential for working with the custom node prestartup script system:

• main.py – Contains execute_prestartup_script() (lines 15-63), the core orchestrator that discovers packages and executes their prestartup scripts.
• folder_paths.py – Defines the custom_nodes path registration (lines 43-45) used to determine which directories the scanner traverses.
• comfy/cli_args.py – Implements the --disable-all-custom-nodes and --whitelist-custom-nodes arguments that gate access to the prestartup phase.
• nodes.py – Loads node classes after the prestartup phase completes, making it the downstream consumer of any environment changes made during prestartup.

Creating a Prestartup Script for Your Custom Node

To utilize the custom node prestartup script system, create a file named prestartup_script.py in your package root. This script runs once before ComfyUI imports your __init__.py.

# custom_nodes/MyExtension/prestartup_script.py

import os
import logging

# Configure environment variables for later use

os.environ["MYEXTENSION_BACKEND"] = "cuda"

# Register global helpers available to your node classes

def preload_resources():
    return "resources loaded"

logging.info("MyExtension prestartup script executed successfully")

After this script runs, the environment variable and helper functions are available when ComfyUI subsequently imports your main node definitions.

Controlling Execution with CLI Flags

Administrators can restrict which custom node prestartup scripts execute using command-line arguments defined in comfy/cli_args.py:

# Disable all custom node prestartup scripts

python main.py --disable-all-custom-nodes

# Whitelist only specific packages when global disable is active

python main.py --disable-all-custom-nodes --whitelist-custom-nodes MyExtension,AnotherSafeNode

When whitelisting, only packages matching the comma-separated names will have their prestartup_script.py files executed. Without the global disable flag, all discovered prestartup scripts run unless blocked by the manager.

Summary

• The custom node prestartup script system executes prestartup_script.py from each package before any node classes load.
• Execution occurs via importlib.util.spec_from_file_location in main.py function execute_prestartup_script().
• The system respects CLI flags --disable-all-custom-nodes and --whitelist-custom-nodes for security control.
• Error handling isolates failures to individual packages without crashing ComfyUI.
• Prestartup scripts are ideal for one-time initialization like setting environment variables or loading large data files.

Frequently Asked Questions

What filename must the prestartup script use?

The system specifically looks for a file named exactly prestartup_script.py in the root of your custom node package folder. Using any other filename will cause ComfyUI to skip the script entirely during the discovery phase in main.py.

When does the prestartup script execute relative to node loading?

The prestartup script executes before ComfyUI imports node classes. Specifically, execute_prestartup_script() runs in main.py immediately after path setup but before the import logic in nodes.py begins loading individual node definitions.

Can a broken prestartup script prevent ComfyUI from starting?

No. The system wraps each script execution in a try-catch block. If your prestartup_script.py raises an exception, ComfyUI logs the error and continues with the next package's startup script, ensuring the application remains stable.

How do I prevent untrusted custom nodes from running prestartup scripts?

Use the CLI flags implemented in comfy/cli_args.py. Run ComfyUI with --disable-all-custom-nodes to block all scripts, or combine it with --whitelist-custom-nodes PackageName to allow only specific trusted packages to execute their prestartup code.

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