> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 启动参数

> ComfyUI main.py 命令行启动参数完整参考

使用 `python main.py` 启动 ComfyUI 时可传入命令行参数。本页记录了 [`comfy/cli_args.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/comfy/cli_args.py) 中定义的全部启动参数。

<Note>
  **Windows 便携版** 用户可在 `.bat` 启动文件（如 `run_nvidia_gpu.bat`）中添加参数。详见 [Windows 便携版安装指南](/zh/installation/comfyui_portable_windows)。
</Note>

在 ComfyUI 目录下运行 `python main.py --help` 可查看内置帮助。可按需组合多个参数：

```bash theme={null}
python main.py --listen 0.0.0.0 --port 8288 --disable-auto-launch --lowvram
```

## 网络与服务器

| 参数                                | 默认值         | 说明                                                                                        |
| --------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `--listen` `[IP]`                 | `127.0.0.1` | 监听的 IP 地址。支持逗号分隔的多个地址（如 `127.2.2.2,127.3.3.3`）。不带值时默认为 `0.0.0.0,::`（监听所有 IPv4 和 IPv6 接口）。 |
| `--port`                          | `8188`      | 监听端口。                                                                                     |
| `--tls-keyfile` `PATH`            | —           | TLS（SSL）密钥文件路径。启用 HTTPS，需配合 `--tls-certfile`。                                             |
| `--tls-certfile` `PATH`           | —           | TLS（SSL）证书文件路径。启用 HTTPS，需配合 `--tls-keyfile`。                                              |
| `--enable-cors-header` `[ORIGIN]` | 关闭          | 启用 CORS。可指定来源；不带值时默认为 `*`（允许所有来源）。                                                        |
| `--max-upload-size`               | `100`       | 最大上传大小（MB）。                                                                               |
| `--enable-compress-response-body` | 关闭          | 启用 HTTP 响应体压缩。                                                                            |

<CodeGroup>
  ```bash theme={null}
  # 监听所有接口（局域网访问）
  python main.py --listen

  # 监听指定 IP
  python main.py --listen 0.0.0.0

  # 自定义端口并启用 HTTPS
  python main.py --port 8443 --tls-keyfile key.pem --tls-certfile cert.pem
  ```
</CodeGroup>

## 目录

| 参数                                  | 默认值         | 说明                                                    |
| ----------------------------------- | ----------- | ----------------------------------------------------- |
| `--base-directory` `PATH`           | ComfyUI 根目录 | models、custom\_nodes、input、output、temp、user 等目录的基础路径。 |
| `--extra-model-paths-config` `PATH` | —           | 加载一个或多个 `extra_model_paths.yaml` 文件。可多次指定。            |
| `--output-directory` `PATH`         | —           | 输出目录。覆盖 `--base-directory`。                           |
| `--temp-directory` `PATH`           | —           | 临时目录。覆盖 `--base-directory`。                           |
| `--input-directory` `PATH`          | —           | 输入目录。覆盖 `--base-directory`。                           |
| `--user-directory` `PATH`           | —           | 用户目录（绝对路径）。覆盖 `--base-directory`。路径必须存在且可读。           |

## 启动与浏览器

| 参数                           | 默认值 | 说明                                               |
| ---------------------------- | --- | ------------------------------------------------ |
| `--auto-launch`              | 关闭  | 启动时自动在默认浏览器中打开 ComfyUI。                          |
| `--disable-auto-launch`      | 关闭  | 禁用自动打开浏览器。                                       |
| `--windows-standalone-build` | 关闭  | Windows 便携版便捷模式。启动时自动打开浏览器（等效于 `--auto-launch`）。 |

<Note>
  `--windows-standalone-build` 会将 `auto_launch` 设为 `true`。`--disable-auto-launch` 会覆盖该行为。以无界面服务器模式运行（不打开浏览器）请使用 `--disable-auto-launch`。
</Note>

```bash theme={null}
# 不打开浏览器运行服务器
python main.py --disable-auto-launch
```

## 设备与 CUDA

| 参数                                  | 默认值            | 说明                                               |
| ----------------------------------- | -------------- | ------------------------------------------------ |
| `--cuda-device` `DEVICE_ID`         | —              | 使用的 CUDA 设备 ID，逗号分隔（如 `0` 或 `0,1`）。其他设备不可见。      |
| `--default-device` `ID`             | —              | 默认设备 ID。其他设备仍可见。                                 |
| `--cuda-malloc`                     | 自动（torch 2.0+） | 启用 cudaMallocAsync。与 `--disable-cuda-malloc` 互斥。 |
| `--disable-cuda-malloc`             | —              | 禁用 cudaMallocAsync。与 `--cuda-malloc` 互斥。         |
| `--directml` `[DEVICE]`             | —              | 使用 torch-directml。可选设备索引；不带值时默认为 `-1`。           |
| `--oneapi-device-selector` `STRING` | —              | Intel 设备的 oneAPI 设备选择器字符串。                       |

## 精度与推理

<Note>
  下方 **全局**、**UNET**、**VAE**、**文本编码器** 各组内的参数互斥，每组同时只能使用一个。
</Note>

### 全局浮点精度

| 参数             | 说明                            |
| -------------- | ----------------------------- |
| `--force-fp32` | 全局强制 fp32。若可提升 GPU 性能请反馈。     |
| `--force-fp16` | 全局强制 fp16。同时设置 `--fp16-unet`。 |

### UNET 精度

| 参数                   | 说明                        |
| -------------------- | ------------------------- |
| `--fp32-unet`        | 以 fp32 运行扩散模型。            |
| `--fp64-unet`        | 以 fp64 运行扩散模型。            |
| `--bf16-unet`        | 以 bf16 运行扩散模型。            |
| `--fp16-unet`        | 以 fp16 运行扩散模型。            |
| `--fp8_e4m3fn-unet`  | 以 fp8（e4m3fn）存储 UNet 权重。  |
| `--fp8_e5m2-unet`    | 以 fp8（e5m2）存储 UNet 权重。    |
| `--fp8_e8m0fnu-unet` | 以 fp8（e8m0fnu）存储 UNet 权重。 |

### VAE 精度

| 参数           | 说明                            |
| ------------ | ----------------------------- |
| `--fp16-vae` | 以 fp16 运行 VAE。可能导致黑图。         |
| `--fp32-vae` | 以 fp32 全精度运行 VAE。             |
| `--bf16-vae` | 以 bf16 运行 VAE。                |
| `--cpu-vae`  | 在 CPU 上运行 VAE（与 VAE 精度参数不互斥）。 |

### 文本编码器精度

| 参数                      | 说明                      |
| ----------------------- | ----------------------- |
| `--fp8_e4m3fn-text-enc` | 以 fp8（e4m3fn）存储文本编码器权重。 |
| `--fp8_e5m2-text-enc`   | 以 fp8（e5m2）存储文本编码器权重。   |
| `--fp16-text-enc`       | 以 fp16 存储文本编码器权重。       |
| `--fp32-text-enc`       | 以 fp32 存储文本编码器权重。       |
| `--bf16-text-enc`       | 以 bf16 存储文本编码器权重。       |

### 其他推理选项

| 参数                        | 默认值 | 说明                                     |
| ------------------------- | --- | -------------------------------------- |
| `--fp16-intermediates`    | 关闭  | 实验性：节点间中间张量使用 fp16 而非 fp32。            |
| `--force-channels-last`   | 关闭  | 推理时强制 channels-last 内存格式。              |
| `--supports-fp8-compute`  | 关闭  | 模拟设备支持 fp8 计算。                         |
| `--enable-triton-backend` | 关闭  | 在 comfy-kitchen 中启用 Triton 后端。默认启动时关闭。 |

## 预览

| 参数                 | 默认值    | 说明                                                |
| ------------------ | ------ | ------------------------------------------------- |
| `--preview-method` | `none` | 采样器节点的预览方式。可选：`none`、`auto`、`latent2rgb`、`taesd`。 |
| `--preview-size`   | `512`  | 预览图像最大尺寸（像素）。                                     |

## 缓存

<Note>
  缓存模式参数互斥。`--cache-ram`、`--cache-classic`、`--cache-lru`、`--cache-none` 只能选其一。
</Note>

| 参数                        | 默认值      | 说明                                                                                                                            |
| ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `--cache-ram` `[GB] [GB]` | 启用（默认模式） | RAM 压力缓存。第一个值：活跃缓存阈值（GB）；可选第二个值：非活跃缓存/固定阈值（GB）。无值时：活跃 = 系统 RAM 的 10%（最小 2 GB，最大 10 GB）；非活跃 = 系统 RAM 的 100%（最大 96 GB）。最多接受两个值。 |
| `--cache-classic`         | —        | 使用旧版激进缓存策略。                                                                                                                   |
| `--cache-lru` `N`         | `0`（关闭）  | LRU 缓存，最多缓存 N 个节点结果。可能占用更多 RAM/VRAM。                                                                                          |
| `--cache-none`            | —        | 降低 RAM/VRAM 占用；每次运行重新执行所有节点。                                                                                                  |

## 注意力机制

<Note>
  交叉注意力方法参数互斥。使用 xformers 时，split 和 quad 注意力会被忽略。
</Note>

| 参数                              | 说明                                                 |
| ------------------------------- | -------------------------------------------------- |
| `--use-split-cross-attention`   | 使用 split 交叉注意力优化。                                  |
| `--use-quad-cross-attention`    | 使用 sub-quadratic 交叉注意力优化。                          |
| `--use-pytorch-cross-attention` | 使用 PyTorch 2.0 交叉注意力。                              |
| `--use-sage-attention`          | 使用 Sage 注意力。                                       |
| `--use-flash-attention`         | 使用 FlashAttention。                                 |
| `--disable-xformers`            | 禁用 xformers。                                       |
| `--force-upcast-attention`      | 强制注意力上转换。若可修复黑图请反馈。与 `--dont-upcast-attention` 互斥。 |
| `--dont-upcast-attention`       | 禁用所有注意力上转换。仅用于调试。                                  |

## VRAM 与内存

<Note>
  VRAM 模式参数（`--gpu-only`、`--highvram`、`--lowvram`、`--novram`、`--cpu`）互斥。
</Note>

| 参数                                | 默认值          | 说明                                      |
| --------------------------------- | ------------ | --------------------------------------- |
| `--gpu-only`                      | —            | 将所有内容（文本编码器、CLIP 等）存储并运行在 GPU 上。        |
| `--highvram`                      | —            | 使用后不将模型卸载到 CPU，保留在 GPU 内存中。             |
| `--lowvram`                       | —            | 启用动态 VRAM 时无效。否则将文本编码器运行在 CPU 上。        |
| `--novram`                        | —            | `--lowvram` 仍不足时使用，最小化 VRAM 占用。         |
| `--cpu`                           | —            | 全部使用 CPU（较慢）。                           |
| `--reserve-vram` `GB`             | 依系统而定        | 为操作系统和其他软件预留的 VRAM（GB）。                 |
| `--async-offload` `[NUM_STREAMS]` | Nvidia 上默认启用 | 异步权重卸载。可选流数量（默认：2）。                     |
| `--disable-async-offload`         | —            | 禁用异步权重卸载。                               |
| `--disable-dynamic-vram`          | —            | 禁用动态 VRAM，使用基于估算的模型加载。                  |
| `--enable-dynamic-vram`           | Nvidia 上自动   | 在默认未启用的系统上启用动态 VRAM。                    |
| `--fast-disk`                     | 关闭           | 优先使用磁盘-backed 动态加载而非未固定 RAM。适合高速 NVMe。  |
| `--force-non-blocking`            | 关闭           | 强制非阻塞张量操作。可能有助于非 Nvidia 系统；可能导致部分工作流异常。 |
| `--disable-smart-memory`          | 关闭           | 积极卸载到 RAM，而非尽量保留在 VRAM 中。               |
| `--disable-pinned-memory`         | 关闭           | 禁用固定内存（pinned memory）。                  |
| `--mmap-torch-files`              | 关闭           | 加载 ckpt/pt 文件时使用 mmap。                  |
| `--disable-mmap`                  | 关闭           | 加载 safetensors 时不使用 mmap。               |

## 性能与调试

| 参数                           | 默认值      | 说明                                                                                                       |
| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `--fast` `[OPT...]`          | 关闭       | 启用可能影响质量或稳定性的实验性优化。单独使用 `--fast` 启用全部。可选项：`fp16_accumulation`、`fp8_matrix_mult`、`cublas_ops`、`autotune`。 |
| `--deterministic`            | 关闭       | 尽可能使用较慢的确定性 PyTorch 算法。不保证所有情况下图像完全一致。                                                                   |
| `--default-hashing-function` | `sha256` | 重复文件名/内容比较使用的哈希函数。可选：`md5`、`sha1`、`sha256`、`sha512`。                                                     |

```bash theme={null}
# 启用全部 fast 优化（实验性）
python main.py --fast

# 仅启用特定优化
python main.py --fast fp16_accumulation cublas_ops
```

## ComfyUI Manager

安装说明请参阅 [ComfyUI-Manager 安装](/zh/manager/install)。

| 参数                           | 说明                                                        |
| ---------------------------- | --------------------------------------------------------- |
| `--enable-manager`           | 启用 ComfyUI-Manager。                                       |
| `--disable-manager-ui`       | 仅禁用 Manager UI 和端点。后台任务（定时安装等）继续运行。需要 `--enable-manager`。 |
| `--enable-manager-legacy-ui` | 使用旧版 Manager UI。需要 `--enable-manager`。                    |

## 自定义节点与 API 节点

| 参数                                     | 默认值 | 说明                                              |
| -------------------------------------- | --- | ----------------------------------------------- |
| `--disable-all-custom-nodes`           | 关闭  | 禁用加载所有自定义节点。                                    |
| `--whitelist-custom-nodes` `FOLDER...` | —   | 在启用 `--disable-all-custom-nodes` 时仍加载的自定义节点文件夹。 |
| `--disable-api-nodes`                  | 关闭  | 禁用 API 节点，并阻止前端与互联网通信。                          |
| `--disable-metadata`                   | 关闭  | 禁用将提示词元数据保存到输出文件。                               |

```bash theme={null}
# 排查自定义节点问题
python main.py --disable-all-custom-nodes

# 仅允许特定自定义节点
python main.py --disable-all-custom-nodes --whitelist-custom-nodes ComfyUI-Manager
```

## 前端与 API

| 参数                             | 默认值                                   | 说明                                                                                             |
| ------------------------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `--front-end-version`          | `comfyanonymous/ComfyUI@latest`       | 前端版本，格式为 `[owner]/[repo]@[version]`。需联网从 GitHub releases 下载。版本可为 `latest` 或 semver（如 `1.0.0`）。 |
| `--front-end-root` `PATH`      | —                                     | 前端目录的本地路径。覆盖 `--front-end-version`。                                                            |
| `--comfy-api-base`             | `https://api.comfy.org`               | ComfyUI API 基础 URL。                                                                            |
| `--database-url`               | `sqlite:///<ComfyUI>/user/comfyui.db` | 数据库 URL。内存数据库使用 `sqlite:///:memory:`。                                                          |
| `--enable-assets`              | 关闭                                    | 启用资产系统（API 路由、数据库同步、后台扫描）。                                                                     |
| `--feature-flag` `KEY[=VALUE]` | —                                     | 设置服务器功能开关。仅 `KEY` 时设为 true。可重复指定。布尔值和数字会自动转换。                                                  |
| `--list-feature-flags`         | —                                     | 以 JSON 输出已知 CLI 功能开关并退出。                                                                       |

```bash theme={null}
# 列出可用功能开关
python main.py --list-feature-flags

# 设置功能开关
python main.py --feature-flag show_signin_button=true
```

## 日志与其他

| 参数                    | 默认值    | 说明                                                                               |
| --------------------- | ------ | -------------------------------------------------------------------------------- |
| `--verbose` `[LEVEL]` | `INFO` | 日志级别。可选：`DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL`。单独使用 `--verbose` 设为 `DEBUG`。 |
| `--log-stdout`        | 关闭     | 将正常进程输出发送到 stdout 而非 stderr。                                                     |
| `--dont-print-server` | 关闭     | 不在控制台打印服务器输出。                                                                    |
| `--multi-user`        | 关闭     | 启用按用户隔离存储。                                                                       |
| `--quick-test-for-ci` | 关闭     | CI 快速启动测试。初始化后立即退出。                                                              |

***

<Note>
  本参考基于 ComfyUI 的 [`comfy/cli_args.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/comfy/cli_args.py)。升级 ComfyUI 后，请运行 `python main.py --help` 或对照本地 [`cli_args.py`](https://github.com/Comfy-Org/ComfyUI/blob/master/comfy/cli_args.py) 检查是否有新增或变更的参数。
</Note>