> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-matt-router-pricing-pika-and-guard.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 启动参数

> ComfyUI 启动参数参考：comfy/cli_args.py 中的全部 main.py 命令行参数，以及如何在 Windows 便携版 .bat 启动器中添加参数。

使用 `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 等目录的基础路径。 |
| `--models-directory` `PATH` | ComfyUI 根目录/models | 模型目录。覆盖 `--base-directory` 中的 models 文件夹。 |
| `--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`），或使用 `all` 保留所有当前可见设备。其他设备不可见。 |
| `--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>
  在 Windows 上，ComfyUI 默认仅使用 GPU 0。要恢复使用所有 GPU，请传入 `--cuda-device all`。
</Note>

## 精度与推理

<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 权重。 |

每个 FP8 参数后缀对应业界 FP8 规范（ONNX / OCP）中的一种 8 位浮点布局：

* **e4m3fn**：4 位指数、3 位尾数。在 NVIDIA Ada Lovelace 及更新 GPU 上，为模型权重提供精度与动态范围的良好平衡。
* **e5m2**：5 位指数、2 位尾数。动态范围比 e4m3fn 更宽，但精度较低。适用于权重幅度变化较大的场景。
* **e8m0fnu**：8 位指数、0 位尾数。动态范围最大，无小数精度。通常用作块级缩放因子（仅能表示 2 的幂）。

### 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 存储文本编码器权重。 |

有关各 FP8 格式后缀的说明，请参见 [UNET 精度](#unet-精度) 小节。

### 其他推理选项

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

## 预览

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

## 缓存

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

| 参数 | 默认值 | 说明 |
| - | - | - |
| `--cache-ram` `[GB] [GB]` | 启用（默认模式） | RAM 压力缓存。第一个值：活跃缓存阈值（GB）；可选第二个值：非活跃缓存/固定阈值（GB）。无值时：活跃 = 系统 RAM 的 10%（最小 2 GB，最大 10 GB）；非活跃 = 系统 RAM 的 100%（最大 128 GB）。最多接受两个值。 |
| `--cache-classic` | — | 使用旧版激进缓存策略。 |
| `--high-ram` | 关闭 | 在内存充足、或更倾向使用页面文件而非重新加载模型的系统上可略微提升性能。同时启用 classic 缓存。 |
| `--cache-lru` `N` | `0`（关闭） | LRU 缓存，最多缓存 N 个节点结果。无硬性上限；受可用 RAM/VRAM 限制。可能占用更多 RAM/VRAM。 |
| `--cache-none` | — | 降低 RAM/VRAM 占用；每次运行重新执行所有节点。 |

<Note>
  ComfyUI 会在同一会话中复用已缓存的节点结果，这正是重复运行更快的原因。如果你希望每次运行都从干净的缓存开始，请使用 `--cache-none`，例如在调试工作流，或需要排除运行之间的缓存复用时。代价是每个节点都会重新执行，生成时间会更长。它是启动参数，需要重启 ComfyUI 才会生效。
</Note>

## 注意力机制

<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。 |
| `--use-ck-attention` | 使用 Comfy Kitchen 注意力。需要硬件支持其 INT8 内核。 |
| `--disable-xformers` | 禁用 xformers。 |
| `--force-upcast-attention` | 强制注意力上转换。若可修复黑图请反馈。与 `--dont-upcast-attention` 互斥。 |
| `--dont-upcast-attention` | 禁用所有注意力上转换。仅用于调试。 |

## VRAM 与内存

异步权重卸载在 Nvidia 和 AMD GPU 上默认启用，动态 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）。 |
| `--vram-headroom` `GB` | `0` | 动态 VRAM 在默认预留之上额外保持空闲的 VRAM 量（GB）。ComfyUI 会尽量让这部分 VRAM 完全空闲不使用，其他应用占用的 VRAM 也计入其中。 |
| `--disable-nvml-pressure` | 关闭 | 动态 VRAM 的内存压力改用 CUDA 报告，而非 NVML。 |
| `--async-offload` `[NUM_STREAMS]` | 在 Nvidia 和 AMD 上启用 | 异步权重卸载。可选流数量（默认：2）。 |
| `--disable-async-offload` | — | 禁用异步权重卸载。 |
| `--disable-dynamic-vram` | — | 禁用动态 VRAM，使用基于估算的模型加载。 |
| `--enable-dynamic-vram` | 在 Nvidia 上自动启用，ROCm 7.14+ | 在默认未启用的系统上启用动态 VRAM。 |
| `--fast-disk` | 关闭 | 优先使用磁盘-backed 动态加载而非未固定 RAM。适合高速 NVMe。 |
| `--disable-fast-disk` | 关闭 | 禁用磁盘-backed 动态加载与卸载，改用未固定 RAM。覆盖 `--fast-disk`。 |
| `--disable-cuda-graphs` | 关闭 | 禁用 CUDA graphs。 |
| `--disable-comfy-compiler` | 关闭 | 禁用 Comfy 模型编译器，包括其 CUDA graph 子功能。 |
| `--assert-graph-breaks` | 关闭 | 遇到 Comfy 模型编译器 graph break 时直接失败。 |
| `--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`。 |
| `--debug-hang` | 关闭 | 在按下 Ctrl-C 时输出堆栈跟踪转储，用于排查卡死问题。 |

```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`。与 `--disable-manager-ui` 互斥。 |

## 自定义节点与 API 节点

| 参数 | 默认值 | 说明 |
| - | - | - |
| `--disable-all-custom-nodes` | 关闭 | 禁用加载所有自定义节点。 |
| `--whitelist-custom-nodes` `FOLDER...` | — | 在启用 `--disable-all-custom-nodes` 时仍加载的自定义节点文件夹。 |
| `--disable-partner-nodes` | 关闭 | 禁用加载合作伙伴节点（付费 API 节点）。前端仍可访问互联网。 |
| `--offline` | 关闭 | 通过附加限制性的 Content-Security-Policy 阻止前端与互联网通信。同时禁用合作伙伴节点。 |
| `--disable-api-nodes` | 关闭 | `--offline` 的已弃用别名。请使用 `--offline`，或使用 `--disable-partner-nodes` 只禁用合作伙伴节点。 |
| `--disable-metadata` | 关闭 | 禁用将提示词元数据保存到输出文件。 |

<Note>
  `--offline` 还会改变浏览器可以加载的内容。该参数会附加一条 Content-Security-Policy，把页面限制在 ComfyUI 自身提供的资源上，因此来自其他源的图片、字体、媒体、框架和网络请求都会被拦截，合作伙伴节点（API 节点）也不会被注册。重启后原本能正常加载的预览或缩略图消失时，先检查启动参数里有没有这个参数，再去排查节点本身。`--disable-partner-nodes` 只会阻止加载合作伙伴节点，前端其余的网络访问保持不变。
</Note>

```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 路由、数据库同步、后台扫描）。 |
| `--enable-asset-hashing` | 关闭 | 扫描资产时计算 blake3 内容哈希。可用于后续的资产可移植功能（去重、跨机器模型解析），代价是启动时间以及大型模型目录下逐个输出的哈希开销。默认关闭。 |
| `--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] [FILE]` | `INFO` | 日志级别。可选：`DEBUG`、`DETAIL`、`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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.