python main.py 启动 ComfyUI 时可传入命令行参数。本页记录了 comfy/cli_args.py 中定义的全部启动参数。
Windows 便携版 用户可在
.bat 启动文件（如 run_nvidia_gpu.bat）中添加参数。详见 Windows 便携版安装指南。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 权重。 |
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 | 预览图像最大尺寸（像素）。 |
缓存
缓存模式参数互斥。
--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。 |
--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 检查是否有新增或变更的参数。