# How the ComfyUI Custom Node Prestartup Script System Works

> Explore the ComfyUI custom node prestartup script system. Learn how prestartup scripts enable one-time initialization, support security flags, and streamline node imports for efficient workflows.

- Repository: [Comfy Org/ComfyUI](https://github.com/Comfy-Org/ComfyUI)
- Tags: internals
- Published: 2026-02-26

---

**ComfyUI executes a [`prestartup_script.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/main.py)** – Contains `execute_prestartup_script()` (lines 15-63), the core orchestrator that discovers packages and executes their prestartup scripts.
- **[`folder_paths.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/folder_paths.py)** – Defines the `custom_nodes` path registration (lines 43-45) used to determine which directories the scanner traverses.
- **[`comfy/cli_args.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/cli_args.py)** – Implements the `--disable-all-custom-nodes` and `--whitelist-custom-nodes` arguments that gate access to the prestartup phase.
- **[`nodes.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/prestartup_script.py) in your package root. This script runs once before ComfyUI imports your [`__init__.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/__init__.py).

```python

# 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`](https://github.com/Comfy-Org/ComfyUI/blob/main/comfy/cli_args.py):

```bash

# 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`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/prestartup_script.py) from each package before any node classes load.
- Execution occurs via `importlib.util.spec_from_file_location` in [`main.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/main.py) immediately after path setup but before the import logic in [`nodes.py`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/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`](https://github.com/Comfy-Org/ComfyUI/blob/main/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.