开发与 API

启动参数

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

官方中文源 / development/comfyui-server/startup-flags.mdx / 固定提交 e433279d

使用 python main.py 启动 ComfyUI 时可传入命令行参数。本页记录了 comfy/cli_args.py 中定义的全部启动参数。

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

bash
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 响应体压缩。
bash
# 监听所有接口（局域网访问）
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

目录

参数 默认值 说明
--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）。
bash
# 不打开浏览器运行服务器
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 设备选择器字符串。

精度与推理

全局浮点精度

参数 说明
--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 精度 小节。

其他推理选项

参数 默认值 说明
--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 预览图像最大尺寸（像素）。

缓存

参数 默认值 说明
--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 限制。可能占用更多 RAM/VRAM。
--cache-none — 降低 RAM/VRAM 占用；每次运行重新执行所有节点。

注意力机制

参数 说明
--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 与内存

参数 默认值 说明
--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
# 启用全部 fast 优化（实验性）
python main.py --fast

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

ComfyUI Manager

安装说明请参阅 ComfyUI-Manager 安装。

参数 说明
--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
# 排查自定义节点问题
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:////user/comfyui.db 数据库 URL。内存数据库使用 sqlite:///:memory:。
--enable-assets 关闭 启用资产系统（API 路由、数据库同步、后台扫描）。
--feature-flag KEY[=VALUE] — 设置服务器功能开关。仅 KEY 时设为 true。可重复指定。布尔值和数字会自动转换。
--list-feature-flags — 以 JSON 输出已知 CLI 功能开关并退出。
bash
# 列出可用功能开关
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 快速启动测试。初始化后立即退出。

官方原文

本页来自 Comfy-Org 官方中文文档的固定版本，并转换为 xueai 静态页面。内容以官方持续更新的页面为准。

内容授权与修改

官方文档采用 GPL-3.0。本站保留许可证、固定提交号和修改说明，不代表 ComfyUI 或 Comfy-Org 对本站背书。

GPL-3.0，来源和修改说明