启动参数

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

Windows 便携版 用户可在 .bat 启动文件（如 run_nvidia_gpu.bat）中添加参数。详见 Windows 便携版安装指南。

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

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 响应体压缩。

# 监听所有接口（局域网访问）
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`）。

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

# 不打开浏览器运行服务器
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 设备选择器字符串。

精度与推理

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

全局浮点精度

参数	说明
`--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、--cache-classic、--cache-lru、--cache-none 只能选其一。

参数	默认值	说明
`--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 占用；每次运行重新执行所有节点。

注意力机制

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

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

VRAM 模式参数（--gpu-only、--highvram、--lowvram、--novram、--cpu）互斥。

参数	默认值	说明
`--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`。

# 启用全部 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`	关闭	禁用将提示词元数据保存到输出文件。

# 排查自定义节点问题
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 功能开关并退出。

# 列出可用功能开关
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 快速启动测试。初始化后立即退出。

本参考基于 ComfyUI 的 comfy/cli_args.py。升级 ComfyUI 后，请运行 python main.py --help 或对照本地 cli_args.py 检查是否有新增或变更的参数。

ComfyUI APIs

CLI

开发自定义节点

注册表(Registry)

规范

网络与服务器

目录

启动与浏览器

设备与 CUDA

精度与推理

全局浮点精度

UNET 精度

VAE 精度

文本编码器精度

其他推理选项

预览

缓存

注意力机制

VRAM 与内存

性能与调试

ComfyUI Manager

自定义节点与 API 节点

前端与 API

日志与其他

​网络与服务器

​目录

​启动与浏览器

​设备与 CUDA

​精度与推理

​全局浮点精度

​UNET 精度

​VAE 精度

​文本编码器精度

​其他推理选项

​预览

​缓存

​注意力机制

​VRAM 与内存

​性能与调试

​ComfyUI Manager

​自定义节点与 API 节点

​前端与 API

​日志与其他

网络与服务器

目录

启动与浏览器

设备与 CUDA

精度与推理

全局浮点精度

UNET 精度

VAE 精度

文本编码器精度

其他推理选项

预览

缓存

注意力机制

VRAM 与内存

性能与调试

ComfyUI Manager

自定义节点与 API 节点

前端与 API

日志与其他