comfy-cli：ComfyUI 的命令行工具

comfy-cli 是一款命令行工具，可帮助用户轻松安装和管理 ComfyUI，这是一个功能强大的开源机器学习框架。借助 comfy-cli，您可以通过终端便捷地快速搭建 ComfyUI、安装软件包以及管理自定义节点。

演示

功能特性

• 🚀 通过一条命令即可轻松安装 ComfyUI
• 📦 无缝管理 ComfyUI 扩展及依赖包
• 🔧 管理自定义节点，扩展 ComfyUI 功能
• 🗄️ 下载检查点并保存模型哈希值
• 💻 跨平台兼容性（Windows、macOS、Linux）
• 📖 详尽的文档与示例
• 🎉 自动为 ComfyUI 安装拉取请求

安装

1. （推荐，但非必需）启用虚拟环境（venv/conda）

2. 要安装 comfy-cli，请确保您的系统已安装 Python 3.9 或更高版本。然后运行以下命令：

   pip install comfy-cli

Shell 自动补全

要在您的 shell 中安装自动补全提示，请运行：

comfy --install-completion

这将使您能够输入 comfy [TAB] 来自动完成命令和选项。

使用方法

安装 ComfyUI

要使用 comfy 安装 ComfyUI，只需运行：

comfy install

此命令将在您的系统上下载并设置最新版本的 ComfyUI 和 ComfyUI-Manager。如果您在已经设置好的 ComfyUI 仓库中运行该命令，则只会更新 comfy.yaml 文件以反映本地设置。

• comfy install --skip-manager：不安装 ComfyUI-Manager 直接安装 ComfyUI。若要使用自定义 Manager 分支或特定版本，请跳过默认安装，并将您自己的安装到工作区的 venv 中：

  comfy install --skip-manager
  # 然后安装您的自定义 Manager：
  pip install -e /path/to/your-manager-fork   # 可编辑安装
  # 或
  pip install comfyui-manager==4.1b8          # 特定版本
  

• comfy --workspace=<path> install：将 ComfyUI 安装到 <path>/ComfyUI。
• comfy install --fast-deps：在首次安装 ComfyUI 时，使用 uv 替代 pip 以加快依赖项解析速度。comfy-cli 内置的解析器会将所有需求（核心 + 自定义节点）编译成一个单独的锁定文件，并从中进行安装。同时还会自动处理 GPU 特定的 PyTorch wheel 选择。
• 对于 comfy install，如果没有提供如 --workspace、--recent 或 --here 等路径指定，则会默认安装在 <HOME>/comfy。

Python 环境处理

当您运行 comfy install 时，comfy-cli 会按照以下优先级为 ComfyUI 依赖项选择 Python 环境：

1. 如果存在活动的 virtualenv 或 conda 环境（VIRTUAL_ENV / CONDA_PREFIX），则直接使用该环境。
2. 如果工作区内已存在 .venv 或 venv 目录，则复用该目录。
3. 否则，选择取决于 comfy-cli 的安装方式：
   • pip install comfy-cli（全局 / 系统 Python）：依赖项将直接安装到同一 Python 环境中。这通常是 Docker 设置中的常见做法。
   • pipx install comfy-cli 或 uv tool install comfy-cli（隔离的工具环境）：会在 ComfyUI 工作区内部创建一个 .venv。请使用 comfy launch 来启动具有正确 Python 环境的 ComfyUI。

指定执行路径

• 您可以通过以下路径指示符来指定命令将作用于的 ComfyUI 路径：

  • comfy --workspace=<path>：从指定工作区中安装的 ComfyUI 运行。
  • comfy --recent：从最近执行或安装的 ComfyUI 运行。
  • comfy --here：从当前目录下的 ComfyUI 运行。

• --workspace、--recent 和 --here 选项不能同时使用。

• 如果没有路径指示符，则按以下优先级执行：

  • 从由 comfy set-default <path> 指定的默认 ComfyUI 路径运行。
  • 从最近执行或安装的 ComfyUI 运行。
  • 从当前目录下的 ComfyUI 运行。

• 示例 1：运行最近执行的 ComfyUI：

  • comfy --recent launch

• 示例 2：在当前目录下的 ComfyUI 上安装一个包：

  • comfy --here node install comfyui-impact-pack

• 示例 3：根据优先级更新自动选择的 ComfyUI 和自定义节点路径：

  • comfy node update all

• 您可以使用 comfy which 命令来检查目标工作区的路径。

  • 例如 comfy --recent which、comfy --here which、comfy which 等。

默认设置

默认设置是指在未为命令指定特定工作区的 ComfyUI 时，将默认执行的选项。

comfy set-default <workspace path> ?[--launch-extras="<extra args>"]

• --launch-extras 选项指定了仅在默认启动时应用的额外参数。然而，如果在启动时指定了额外参数，则此设置将被忽略。

启动 ComfyUI

Comfy 提供了一些命令，方便您轻松运行已安装的 ComfyUI。

comfy launch

• 使用默认 ComfyUI 选项运行：

  comfy launch -- <extra args...>

  comfy launch -- --cpu --listen 0.0.0.0

  • 当您手动配置额外选项时，通过 set-default 设置的额外选项将被覆盖。

• 后台运行：

  comfy launch --background

  comfy --workspace=~/comfy launch --background -- --listen 10.0.0.10 --port 8000

  • 使用 --background 启动的实例会显示在 comfy env 的“后台 ComfyUI”部分，仅提供对单个后台实例的管理功能。
  • 由于 comfy env 中的“Comfy Server Running”只显示默认端口 8188，因此不会显示在其他端口上运行的 ComfyUI。
  • 可以使用 comfy stop 停止后台运行的 ComfyUI。

• 使用特定的 Pull Request 运行 ComfyUI：

  comfy install --pr "#1234"

  comfy install --pr "jtydhr88:load-3d-nodes"

  comfy install --pr "https://github.com/comfyanonymous/ComfyUI/pull/1234"

  • 如果您想使用特定的 Pull Request 运行 ComfyUI，可以使用 --pr 选项。这将自动安装指定的 Pull Request 并使用它来运行 ComfyUI。
  • 注意：--pr 选项不能与 --version 或 --commit 同时使用，否则会被拒绝。

• 测试前端 Pull Request：

  comfy launch --frontend-pr "#456"
  comfy launch --frontend-pr "username:branch-name"
  comfy launch --frontend-pr "https://github.com/Comfy-Org/ComfyUI_frontend/pull/456"
  

  • --frontend-pr 选项允许您通过自动克隆、构建并在此会话中使用该前端来测试前端 PR。
  • 要求：必须安装 Node.js 和 npm 才能构建前端。
  • 构建结果会被缓存，以便快速切换 PR——后续再次使用同一 PR 时会立即生效。
  • 每个 PR 只用于当前的启动会话。正常启动时仍使用默认前端。

  管理 PR 缓存：

  comfy pr-cache list              # 列出缓存的 PR 构建
  comfy pr-cache clean             # 清除所有缓存的构建
  comfy pr-cache clean 456         # 清除特定 PR 的缓存
  

  • 缓存会在 7 天后自动过期。
  • 最多保留 10 个 PR 构建（最旧的会自动移除）。
  • 缓存限制有助于管理磁盘空间，同时保持最近的构建可用。

管理自定义节点

comfy 提供了一种便捷的方式来管理自定义节点，以扩展 ComfyUI 的功能。以下是一些示例：

• 显示自定义节点的信息：

comfy node [show|simple-show] [installed|enabled|not-installed|disabled|all|snapshot|snapshot-list]
                             ?[--channel <channel name>]
                             ?[--mode [remote|local|cache]]

• comfy node show all --channel recent

  comfy node simple-show installed

  comfy node update all

  comfy node install comfyui-impact-pack

• 管理快照：

  comfy node save-snapshot

  comfy node restore-snapshot <snapshot name>

• 安装依赖：

  comfy node install-deps --deps=<deps .json file>

  comfy node install-deps --workflow=<workflow .json/.png file>

• 生成依赖：

  comfy node deps-in-workflow --workflow=<workflow .json/.png file> --output=<output deps .json file>

统一依赖解析 (--uv-compile)

需要 ComfyUI-Manager v4.1+。与其为每个节点单独使用 pip install 安装依赖，不如使用 --uv-compile 将任务交给 ComfyUI-Manager 的统一解析器，通过 uv pip compile 批量解析所有自定义节点的依赖，并具备跨节点冲突检测功能——它可以识别哪些节点包存在不兼容的依赖及其原因。

• 使用统一解析安装：

  comfy node install comfyui-impact-pack --uv-compile

• 适用于：install、reinstall、update、fix、restore-snapshot、restore-dependencies、install-deps

• 单独运行（解析所有现有自定义节点的依赖）：

  comfy node uv-sync

• --uv-compile 与 --fast-deps 和 --no-deps 互斥。

• 若要将 --uv-compile 设为所有命令的默认设置，请参阅下方的 [uv-compile 默认设置]。

• 使用 --no-uv-compile 可以覆盖单个命令的默认设置：

  comfy node install comfyui-impact-pack --no-uv-compile

--fast-deps 与 --uv-compile

这两个标志都使用 uv 来加速依赖解析，但它们的工作方式有所不同：

	--fast-deps	--uv-compile
解析器	comfy-cli 内置的 (DependencyCompiler)	ComfyUI-Manager (UnifiedDepResolver)
适用范围	comfy install、comfy node install/reinstall	仅限自定义节点相关命令
冲突处理	交互式提示选择版本	自动检测并标注导致冲突的节点
默认配置	无	是（comfy manager uv-compile-default true）
所需条件	仅需 uv	需要 ComfyUI-Manager v4.1+

何时使用哪个：

• 对于初次安装 ComfyUI 并希望使用 uv 时：comfy install --fast-deps
• 对于使用 Manager v4.1+ 管理自定义节点时：--uv-compile（推荐）
• 对于使用较旧版本 Manager 管理自定义节点时：--fast-deps

自定义节点二分法

如果您遇到的问题仅在启用自定义节点时出现，并且想找出是哪个或哪些自定义节点导致了问题，那么二分法工具可以帮助您定位具体问题节点。

• comfy node bisect start：开始一个新的二分法会话，可选传入 ComfyUI 启动参数。执行命令时会自动将起始状态标记为“坏”，并将当时启用的所有节点作为测试集。
• comfy node bisect good：将当前活动节点集合标记为“好”，表示问题不在该测试集中。
• comfy node bisect bad：将当前活动节点集合标记为“坏”，表示问题在该测试集中。
• comfy node bisect reset：重置当前的二分法会话。

管理模型

• 模型下载

  comfy model download --url <URL> ?[--relative-path <PATH>] ?[--set-civitai-api-token <TOKEN>] ?[--set-hf-api-token <TOKEN>]

  • URL：CivitAI 页面、Hugging Face 文件 URL 等...
  • 您也可以通过 CIVITAI_API_TOKEN 和 HF_API_TOKEN 环境变量指定您的 API 令牌。优先级顺序为：--set-X-token（始终最高）、环境变量（如果存在），最后是您配置文件中之前使用 --set-X-token 时保存的令牌（会记住您最近设置的令牌值）。
  • 通过环境变量提供的令牌绝不会持久化存储在您的配置文件中。它们旨在以安全且便捷的方式提供临时密钥。

• 删除模型

  comfy model remove ?[--relative-path <PATH>] --model-names <模型名称>

• 列出模型

  comfy model list ?[--relative-path <PATH>]

管理 ComfyUI-Manager

• 完全禁用 ComfyUI-Manager（不向 ComfyUI 传递管理器标志）：

  comfy manager disable

• 启用带有新 GUI 的 ComfyUI-Manager：

  comfy manager enable-gui

• 启用不带 GUI 的 ComfyUI-Manager（管理器运行但 UI 隐藏）：

  comfy manager disable-gui

• 启用带有旧版 GUI 的 ComfyUI-Manager：

  comfy manager enable-legacy-gui

• 清除预留的启动操作：

  comfy manager clear

• 将旧版通过 Git 克隆的 ComfyUI-Manager 迁移到 pip 包：

  comfy manager migrate-legacy

默认启用 uv-compile

将 --uv-compile 设置为所有自定义节点操作的默认行为：

comfy manager uv-compile-default true

启用后，所有节点命令（install、reinstall、update、fix、restore-snapshot、restore-dependencies、install-deps）都会自动使用 --uv-compile。如需覆盖此设置，可在单个命令中使用 --no-uv-compile。

要禁用：

comfy manager uv-compile-default false

测试功能：comfy-lock.yaml 的格式（开发中）

basic:

models:
  - model: [模型名称]
    url: [来源网址，例如 https://huggingface.co/...]
    paths: [模型路径列表]
      - path: [模型路径]
      - path: [模型路径]
    hashes: [模型哈希值]
      - hash: [哈希值]
        type: [AutoV1、AutoV2、SHA256、CRC32 和 Blake3]
    type: [模型类型，例如 diffuser、lora 等]

  - model:
  ...

# 与 ComfyUI-Manager 的 .yaml 快照兼容
custom_nodes:
  comfyui: [提交哈希]
  file_custom_nodes:
  - disabled: [布尔值]
    filename: [.py 文件名]
    ...
  git_custom_nodes:
    [git URL]:
      disabled: [布尔值]
      hash: [提交哈希]
    ...

分析数据

我们使用 Mixpanel 跟踪分析数据，以帮助我们了解使用模式并确定工作重点。首次下载 CLI 时，系统会请求您同意收集数据。如果您希望随时退出：

comfy tracking disable

您可以在此处查看使用情况：Mixpanel 板

贡献

我们欢迎对 comfy-cli 的贡献！如果您有任何想法、建议或错误报告，请在我们的 GitHub 仓库 中提交问题。如果您想贡献代码，请先 fork 该仓库，然后提交 pull request。

更多详情请参阅 开发指南。

许可证

comfy 采用 GNU 通用公共许可证 v3.0 发布。

支持

如果您在使用 comfy-cli 时遇到任何问题或有疑问，请在我们的 GitHub 仓库中 提交问题，或通过 Discord 联系我们。我们将竭诚为您提供帮助！

祝您使用 ComfyUI 和 comfy-cli 体验愉快！🎉

comfy-cli 快速上手指南

comfy-cli 是一个命令行工具，旨在帮助用户轻松安装、管理和运行 ComfyUI。它支持跨平台（Windows, macOS, Linux），提供一键安装、自定义节点管理及依赖解析等功能。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Windows、macOS 或 Linux。
• Python 版本：必须安装 Python 3.9 或更高版本。
• 推荐环境：建议先创建并激活虚拟环境（如 venv 或 conda），以避免依赖冲突（非强制，但推荐）。

  # 示例：创建 venv
  python -m venv venv
  # Windows 激活
  venv\Scripts\activate
  # macOS/Linux 激活
  source venv/bin/activate
  

• 可选加速：国内用户若遇到下载慢的问题，可配置 pip 国内镜像源（如清华源）：

  pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
  

安装步骤

1. 安装 comfy-cli 使用 pip 进行安装：

   pip install comfy-cli
   

2. 启用命令自动补全（可选） 安装后，运行以下命令以在终端中启用命令和选项的自动补全功能：

   comfy --install-completion
   

   启用后，输入 comfy 后按 Tab 键即可自动提示后续命令。

基本使用

1. 安装 ComfyUI

这是最常用的命令，它将下载并设置最新版本的 ComfyUI 及 ComfyUI-Manager。默认安装路径为 <用户主目录>/comfy。

comfy install

• 指定安装路径：

  comfy --workspace=/path/to/your/dir install
  

• 使用更快的依赖解析（推荐，需安装 uv）：

  comfy install --fast-deps
  

• 跳过 Manager 安装（如需使用特定版本或 fork 版）：

  comfy install --skip-manager
  

2. 启动 ComfyUI

安装完成后，直接运行以下命令即可启动 ComfyUI：

comfy launch

• 传递额外参数（例如监听所有 IP）：

  comfy launch -- --listen 0.0.0.0
  

• 后台运行：

  comfy launch --background
  

• 测试前端 PR（需安装 Node.js）：

  comfy launch --frontend-pr "#456"
  

3. 管理自定义节点 (Custom Nodes)

comfy-cli 提供了便捷的节点管理命令：

• 安装节点：

  comfy node install comfyui-impact-pack
  

• 更新所有节点：

  comfy node update all
  

• 查看已安装的节点：

  comfy node simple-show installed
  

• 统一依赖解析（推荐用于解决依赖冲突，需 ComfyUI-Manager v4.1+）：

  comfy node install <node-name> --uv-compile
  

4. 指定工作区

如果系统中安装了多个 ComfyUI，可以通过以下标识指定操作对象：

• --workspace=<path>：指定具体路径。
• --recent：针对最近运行或安装的实例。
• --here：针对当前目录下的实例。

示例：更新当前目录下的 ComfyUI 节点：

comfy --here node update all

示例：查看目标工作区路径：

comfy which