ComfyPilotComfyPilot
文档 / 开发 / ComfyUI 启动参数：命令行参考

ComfyUI 启动参数：命令行参考

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

开发 startup-flags 更新于 2026-11-13

查看官方原文

ComfyUI 启动参数：命令行参考

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

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

[!NOTE] 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 接口）。
--port8188监听端口。
--tls-keyfile PATH—TLS（SSL）密钥文件路径。启用 HTTPS，需配合 --tls-certfile。
--tls-certfile PATH—TLS（SSL）证书文件路径。启用 HTTPS，需配合 --tls-keyfile。
--enable-cors-header [ORIGIN]关闭启用 CORS。可指定来源；不带值时默认为 *（允许所有来源）。
--max-upload-size100最大上传大小（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 PATHComfyUI 根目录models、custom\_nodes、input、output、temp、user 等目录的基础路径。
--models-directory PATHComfyUI 根目录/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-assets 会覆盖资产系统。以无界面服务器模式运行（不打开浏览器）请使用 --disable-auto-launch。
# 不打开浏览器运行服务器
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 互斥。
--oneapi-device-selector STRING—Intel 设备的 oneAPI 设备选择器字符串。
[!NOTE] 在 Windows 上，ComfyUI 默认仅使用 GPU 0。要恢复使用所有 GPU，请传入 --cuda-device all。

精度与推理

[!NOTE] 下方 全局、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 后端。默认启动时关闭。
--disable-triton-backend关闭强制禁用 comfy-kitchen 的 Triton 后端，覆盖 --enable-triton-backend。

预览

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

缓存

[!NOTE] 缓存模式参数互斥。--cache-ram、--cache-classic、--high-ram、--cache-lru、--cache-none 只能选其一。
参数默认值说明
--cache-ram [GB] [GB]启用（默认模式）RAM 压力缓存。第一个值：活跃缓存阈值（GB）；可选第二个值：非活跃缓存/固定阈值（GB）。无值时：活跃 = 系统 RAM 的 10%（最小 2 GB，最大 10 GB）；非活跃 = 系统 RAM 的 100%（最大 128 GB）。最多接受两个值。
--cache-classic—使用旧版激进缓存策略。
--high-ram关闭在内存充足、或更倾向使用页面文件而非重新加载模型的系统上可略微提升性能。同时启用 classic 缓存。
--cache-lru N0（关闭）LRU 缓存，最多缓存 N 个节点结果。无硬性上限；受可用 RAM/VRAM 限制。可能占用更多 RAM/VRAM。
--cache-none—降低 RAM/VRAM 占用；每次运行重新执行所有节点。
[!NOTE] ComfyUI 会在同一会话中复用已缓存的节点结果，这正是重复运行更快的原因。如果你希望每次运行都从干净的缓存开始，请使用 --cache-none，例如在调试工作流，或需要排除运行之间的缓存复用时。代价是每个节点都会重新执行，生成时间会更长。它是启动参数，需要重启 ComfyUI 才会生效。

注意力机制

[!NOTE] 交叉注意力方法参数互斥。使用 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。
--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）互斥。
参数默认值说明
--gpu-only—将所有内容（文本编码器、CLIP 等）存储并运行在 GPU 上。
--highvram—使用后不将模型卸载到 CPU，保留在 GPU 内存中。
--lowvram—启用动态 VRAM 时无效。否则将文本编码器运行在 CPU 上。
--novram—--lowvram 仍不足时使用，最小化 VRAM 占用。
--cpu—全部使用 CPU（较慢）。
--reserve-vram GB依系统而定为操作系统和其他软件预留的 VRAM（GB）。
--vram-headroom GB0动态 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-diskfalse强制使用磁盘支持的动态加载与卸载，而非未固定 RAM。适合高速 NVMe。当既未设置本参数也未设置 --disable-fast-disk 时，若每个模型文件都位于检测为高速的存储上，则自动启用磁盘支持的加载与卸载。
--disable-fast-disk关闭禁用磁盘支持的动态加载与卸载，改用未固定 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-functionsha256重复文件名/内容比较使用的哈希函数。可选：md5、sha1、sha256、sha512。
--debug-hang关闭在按下 Ctrl-C 时输出堆栈跟踪转储，用于排查卡死问题。
# 启用全部 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。与 --disable-manager-ui 互斥。

自定义节点与 API 节点

参数默认值说明
--disable-all-custom-nodes关闭禁用加载所有自定义节点。
--whitelist-custom-nodes FOLDER...—在启用 --disable-all-custom-nodes 时仍加载的自定义节点文件夹。
--disabled-nodes-config PATH—指向列出要禁用的节点 ID 的 YAML 文件的路径。该文件必须包含一个 disabled_nodes 列表，其元素为节点 ID 字符串。
--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 只会阻止加载合作伙伴节点，前端其余的网络访问保持不变。
# 排查自定义节点问题
python main.py --disable-all-custom-nodes

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

前端与 API

参数默认值说明
--front-end-versioncomfyanonymous/ComfyUI@latest前端版本，格式为 [owner]/[repo]@[version]。需联网从 GitHub releases 下载。版本可为 latest 或 semver（如 1.0.0）。
--front-end-root PATH—前端目录的本地路径。覆盖 --front-end-version。
--comfy-api-basehttps://api.comfy.orgComfyUI API 基础 URL。
--database-urlsqlite:///<ComfyUI>/user/comfyui.db数据库 URL。内存数据库使用 sqlite:///:memory:。
--enable-assets关闭启用资产系统（API 路由、数据库同步、后台扫描）。
--disable-assets关闭即使开启了 --enable-assets 或 --windows-standalone-build，也禁用资产系统。
--enable-asset-hashing关闭扫描资产时计算 blake3 内容哈希。可用于后续的资产可移植功能（去重、跨机器模型解析），代价是启动时间以及大型模型目录下逐个输出的哈希开销。默认关闭；需要先启用资产系统（--enable-assets 或 --windows-standalone-build）。
--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] [FILE]INFO日志级别。可选：DEBUG、DETAIL、INFO、WARNING、ERROR、CRITICAL。单独使用 --verbose 设为 DEBUG。在级别后加上文件路径可同时把该级别日志写入文件；该参数可重复指定，以同时配置控制台与文件输出。
--log-stdout关闭将正常进程输出发送到 stdout 而非 stderr。
--dont-print-server关闭不在控制台打印服务器输出。
--disable-product-tips关闭隐藏控制台中关于 Comfy-Org 商业产品与部署的提示。等同于设置 COMFYUI_DISABLE_PRODUCT_TIPS=1。设置 CI、使用 --dont-print-server 或 --windows-standalone-build 时同样不会显示提示。
--multi-user关闭启用按用户隔离存储。
--quick-test-for-ci关闭CI 快速启动测试。初始化后立即退出。
[!NOTE] 本参考基于 ComfyUI 的 comfy/cli_args.py。升级 ComfyUI 后，请运行 python main.py --help 或对照本地 cli_args.py 检查是否有新增或变更的参数。