ComfyScript

ComfyScript 是一个用于 ComfyUI 的 Python 前端和库。

它具有以下使用场景：

• 作为 ComfyUI 工作流的 人类可读格式。

  这使得比较和重用工作流的不同部分变得容易。此外，由于许多大型语言模型能够较好地处理 Python 代码，因此也可以训练这些模型来生成工作流。这种方法比仅仅让 LLM 提供一些硬编码参数更为强大。

  脚本可以自动从 ComfyUI 的工作流中转换而来。详情请参阅 转译器。

• 直接运行脚本以生成图像。

  与使用 Web UI 相比，这样做的一大优势是可以将 Python 代码与 ComfyUI 的节点混合使用，例如进行循环、调用库函数以及轻松封装自定义节点。这还使得添加交互变得更加容易，因为用户界面和逻辑都可以用 Python 编写。另外，有些人可能更习惯于简单的 Python 代码，而不是基于图的 GUI。[^graph-gui]

  详情请参阅 运行时。脚本可以在本地或通过远程 ComfyUI 服务器执行。

• 将 ComfyUI 用作函数库。

  使用 ComfyScript，可以将 ComfyUI 的节点当作函数来开展机器学习研究、在其他项目中重用节点、调试自定义节点，并优化缓存以加快工作流的运行速度。

  详情请参阅运行时的 真实模式。

• 使用脚本生成 ComfyUI 的工作流。

  脚本还可以用来生成 ComfyUI 的工作流，然后在 Web UI 或其他地方使用。这样就可以利用循环生成庞大的工作流，而手动创建这些工作流可能会非常耗时或不切实际。详情请参阅 工作流生成。此外，还可以从 ComfyScript 生成的图像中加载工作流。

• 通过运行带有某些桩代码的脚本获取所需信息。

  详情请参阅 工作流信息检索。

• 在没有 Web UI 的情况下，将 ComfyUI 的 Web UI 格式的工作流转换为 API 格式。

文档

• 简介（本页）
• 运行时
• 图像
• 模型
• 节点
  • 节点兼容性
  • 附加节点
• 转译器
• 用户界面
  • ipywidgets 界面
  • Solara 界面
• 示例
• 与 ComfyUI-to-Python-Extension 的区别

安装

仅安装 ComfyScript 包

如果您只想将 ComfyScript 与外部 ComfyUI 服务器一起使用，例如使用云端 ComfyUI 服务器并开发应用程序或库：

python -m pip install -U "comfy-script[default]"

from comfy_script.runtime import *
# ComfyUI 服务器/路径
# 或：load(r'path/to/ComfyUI')
load('http://127.0.0.1:8188/')
from comfy_script.runtime.nodes import *

with Workflow(wait=True):
    image = EmptyImage()
    images = util.get_images(image, save=True)

uv run examples/uv.py

# /// script
# requires-python = ">=3.9"
# dependencies = [
#     "comfy-script[default]",
# ]
# ///
from comfy_script.runtime import *
load('http://127.0.0.1:8188/')
from comfy_script.runtime.nodes import *

with Workflow(wait=True):
    image = EmptyImage()
    images = util.get_images(image, save=True)

与 ComfyUI 一起安装

如果您已经安装了 Python 和 ComfyUI：

python -m pip install comfy-cli
comfy --here install

cd ComfyUI/custom_nodes
git clone https://github.com/Chaoses-Ib/ComfyScript.git
cd ComfyScript
python -m pip install -e ".[default]"

cd ComfyUI/custom_nodes/ComfyScript
git pull
python -m pip install -e ".[default]"

与 ComfyUI 及 uv venv 一起安装

如果您尚未安装 Python 或 ComfyUI，可以使用快速的 Python 包和项目管理工具 uv 来同时安装 ComfyUI 和 ComfyScript：

mkdir ComfyUI
cd ComfyUI
uv venv --seed --python 3.12
uv pip install comfy-cli
uv run comfy --workspace . install

# （可选）启动 ComfyUI 进行测试
# uv run main.py

git clone https://github.com/Chaoses-Ib/ComfyScript.git ./custom_nodes/ComfyScript
uv pip install -e "./custom_nodes/ComfyScript[default]"

git -C "./custom_nodes/ComfyScript" pull
uv pip install -e "./custom_nodes/ComfyScript[default]"

cd ComfyUI
# Windows
.\.venv\Scripts\activate
# Linux
source .venv/bin/activate

使用 ComfyUI 包进行安装

如果您想将 ComfyUI 作为 pip 包安装：

python -m pip install -U "comfy-script[default]"

python -m pip install --no-build-isolation git+https://github.com/hiddenswitch/ComfyUI.git@95a12f42e2b0c78202af10f2337009bd769157a7

容器

• @the-dream-machine 提供的 Modal（ComfyUI + Comfy-Cli）
• promeG/comfyui：ComfyUI Docker 镜像

其他

如遇到任何问题，请参阅 故障排除 和 VS Code。卸载方法请参考 卸载指南。

转译器

转译器可以将 ComfyUI 的工作流转换为 ComfyScript。

当 ComfyScript 以自定义节点的形式安装时，SaveImage 等节点会自动钩子，将脚本保存为图像的元数据，并同时在终端中打印该脚本。

如果您是在 ComfyUI 外部安装了 ComfyScript，仍然可以通过以下方式使用转译器：

• CLI

  python -m comfy_script.transpile "workflow.json" --api http://127.0.0.1:8188/
  

  或者无需安装 ComfyScript，直接使用 uv：

  uvx --from "comfy-script[default]" python -m comfy_script.transpile "workflow.json" --api http://127.0.0.1:8188/
  

• Python 代码
• Jupyter Notebook / Web：MetadataViewer

例如，以下是 ComfyUI 中的一个工作流：

由此转换得到的 ComfyScript 如下：

model, clip, vae = CheckpointLoaderSimple('v1-5-pruned-emaonly.ckpt')
conditioning = CLIPTextEncode('美丽的风景 自然 玻璃瓶 风景画, , 紫色星系瓶,', clip)
conditioning2 = CLIPTextEncode('文字 水印', clip)
latent = EmptyLatentImage(512, 512, 1)
latent = KSampler(model, 156680208700286, 20, 8, 'euler', 'normal', conditioning, conditioning2, latent, 1)
image = VAEDecode(latent, vae)
SaveImage(image, 'ComfyUI')

如果一个工作流中有两个或多个 SaveImage 节点，每个节点只会翻译其必要的输入参数生成脚本。例如，以下是一个两步的 txt2img（高分辨率修复）工作流：

针对这两个保存图像分别生成的 ComfyScript 如下：

1. model, clip, vae = CheckpointLoaderSimple('v2-1_768-ema-pruned.ckpt')
   conditioning = CLIPTextEncode('杰作 HDR 维多利亚风格女性肖像画，金发，山地自然，蓝天', clip)
   conditioning2 = CLIPTextEncode('手部缺陷 文字 水印', clip)
   latent = EmptyLatentImage(768, 768, 1)
   latent = KSampler(model，89848141647836，12，8，'dpmpp_sde', 'normal', conditioning，conditioning2，latent，1)
   image = VAEDecode(latent，vae)
   SaveImage(image，'ComfyUI')
   

2. model，clip，vae = CheckpointLoaderSimple('v2-1_768-ema-pruned.ckpt')
   conditioning = CLIPTextEncode('杰作 HDR 维多利亚风格女性肖像画，金发，山地自然，蓝天', clip)
   conditioning2 = CLIPTextEncode('手部缺陷 文字 水印', clip)
   latent = EmptyLatentImage(768，768，1)
   latent = KSampler(model，89848141647836，12，8,'dpmpp_2m', 'simple', conditioning，conditioning2，latent，1)
   latent2 = LatentUpscale(latent，'nearest-exact', 1152，1152，'disabled')
   latent2 = KSampler(model，469771404043268，14，8，'dpmpp_2m', 'simple', conditioning，conditioning2，latent2，0.5)
   image = VAEDecode(latent2，vae)
   SaveImage(image，'ComfyUI')
   

脚本对比：

运行时

使用运行时，可以按如下方式运行 ComfyScript：

from comfy_script.runtime import *
load()
from comfy_script.runtime.nodes import *

with Workflow():
    model, clip, vae = CheckpointLoaderSimple('v1-5-pruned-emaonly.ckpt')
    conditioning = CLIPTextEncode('美丽的风景 自然 玻璃瓶 风景画, , 紫色星系瓶,', clip)
    conditioning2 = CLIPTextEncode('文字，水印', clip)
    latent = EmptyLatentImage(512, 512, 1)
    latent = KSampler(model, 156680208700286, 20, 8, 'euler', 'normal', conditioning, conditioning2, latent, 1)
    image = VAEDecode(latent, vae)
    SaveImage(image, 'ComfyUI')
    
    # 若要获取 `image` 而不是保存它，可将 `SaveImage` 替换为：
    # images = util.get_images(image)
    # `images` 的类型为 `list[PIL.Image.Image]`

Jupyter Notebook 示例可在 examples/runtime.ipynb 中找到。

• 加载后，将在 comfy_script/runtime/nodes.pyi 中生成类型存根文件。主流代码编辑器（例如 VS Code）可以利用这些存根文件来辅助编码：

  对于所有提供值列表的参数，都会生成 Python 枚举。因此，您无需再复制粘贴类似 'v1-5-pruned-emaonly.ckpt' 的字符串，而是可以直接使用：

  Checkpoints.v1_5_pruned_emaonly
  # 或
  CheckpointLoaderSimple.ckpt_name.v1_5_pruned_emaonly
  

  嵌入向量也可以通过 Embeddings.my_embedding 来引用，这等价于 'embedding:my-embedding'。有关详细信息，请参阅 枚举。

  如果类型存根对您不起作用（无法获得与截图相似的效果），请参阅 类型存根不工作。

• 运行时默认是异步的。您可以将多个任务加入队列，而无需等待第一个任务完成。一个守护线程会监控并报告队列中剩余的任务以及当前进度，例如：

  队列剩余：1
  队列剩余：2
  100%|██████████████████████████████████████████████████| 20/20
  队列剩余：1
  100%|██████████████████████████████████████████████████| 20/20
  队列剩余：0
  

  此外，还提供了一些控制功能：

  # 中断当前任务
  queue.cancel_current()
  # 清空队列
  queue.cancel_remaining()
  # 中断当前任务并清空队列
  queue.cancel_all()
  # 当队列为空时调用回调函数
  queue.when_empty(callback)
  
  # 使用 Workflow 时：
  Workflow(cancel_remaining=True)
  Workflow(cancel_all=True)
  

如果您之前使用过 ComfyUI 的 Web UI，请参阅 与 ComfyUI Web UI 的区别，更多关于运行时的详细信息请参阅 运行时文档。

示例

绘图

with Workflow():
    seed = 0
    pos = '天空, 1位女孩, 微笑'
    neg = 'embedding:easynegative'
    model, clip, vae = CheckpointLoaderSimple(Checkpoints.AOM3A1B_orangemixs)
    model2, clip2, vae2 = CheckpointLoaderSimple(Checkpoints.CounterfeitV25_25)
    model2 = TomePatchModel(model2, 0.5)
    for color in '红色', '绿色', '蓝色':
        latent = EmptyLatentImage(440, 640)
        latent = KSampler(model, seed, steps=15, cfg=6, sampler_name='uni_pc',
                          positive=CLIPTextEncode(f'{color}, {pos}', clip), negative=CLIPTextEncode(neg, clip),
                          latent_image=latent)
        SaveImage(VAEDecode(latent, vae2), f'{seed} {color}')
        latent = LatentUpscaleBy(latent, scale_by=2)
        latent = KSampler(model2, seed, steps=15, cfg=6, sampler_name='uni_pc',
                          positive=CLIPTextEncode(f'{color}, {pos}', clip2), negative=CLIPTextEncode(neg, clip2),
                          latent_image=latent, denoise=0.6)
        SaveImage(VAEDecode(latent, vae2), f'{seed} {color} 高分辨率')

自动队列

当队列为空时，自动将新工作流加入队列。

例如，可以使用 comfyui-photoshop（目前还有一些小问题）来实现：当 Photoshop 中的图像发生变化时，自动执行 img2img 操作：

def f(wf):
    seed = 0
    pos = '1位女孩, 生气, 中指'
    neg = 'embedding:easynegative'
    model, clip, vae = CheckpointLoaderSimple(Checkpoints.CounterfeitV25_25)
    image, width, height = PhotoshopToComfyUI(wait_for_photoshop_changes=True)
    latent = VAEEncode(image, vae)
    latent = LatentUpscaleBy(latent, scale_by=1.5)
    latent = KSampler(model, seed, steps=15, cfg=6, sampler_name='uni_pc',
                        positive=CLIPTextEncode(pos, clip), negative=CLIPTextEncode(neg, clip),
                        latent_image=latent, denoise=0.8)
    PreviewImage(VAEDecode(latent, vae))
queue.when_empty(f)

截图：

选择与处理

例如，一次生成 3 张图片，然后让用户决定哪些需要进行高分辨率修复：

import ipywidgets as widgets

queue.watch_display(False)

latents = []
image_batches = []
with Workflow():
    seed = 0
    pos = '天空, 1位女孩, 微笑'
    neg = 'embedding:easynegative'
    model, clip, vae = CheckpointLoaderSimple(Checkpoints.AOM3A1B_orangemixs)
    model2, clip2, vae2 = CheckpointLoaderSimple(Checkpoints.CounterfeitV25_25)
    for color in '红色', '绿色', '蓝色':
        latent = EmptyLatentImage(440, 640)
        latent = KSampler(model, seed, steps=15, cfg=6, sampler_name='uni_pc',
                          positive=CLIPTextEncode(f'{color}, {pos}', clip), negative=CLIPTextEncode(neg, clip),
                          latent_image=latent)
        latents.append(latent)
        image_batches.append(SaveImage(VAEDecode(latent, vae), f'{seed} {color}'))

grid = widgets.GridspecLayout(1, len(image_batches))
for i, image_batch in enumerate(image_batches):
    image_batch = image_batch.wait()
    image = widgets.Image(value=image_batch[0]._repr_png_())

    button = widgets.Button(description=f'高分辨率修复 {i}')
    def hiresfix(button, i=i):
        print(f'第 {i} 张图片被选中')
        with Workflow():
            latent = LatentUpscaleBy(latents[i], scale_by=2)
            latent = KSampler(model2, seed, steps=15, cfg=6, sampler_name='uni_pc',
                            positive=CLIPTextEncode(pos, clip2), negative=CLIPTextEncode(neg, clip2),
                            latent_image=latent, denoise=0.6)
            image_batch = SaveImage(VAEDecode(latent, vae2), f'{seed} 高分辨率')
        display(image_batch.wait())
    button.on_click(hiresfix)

    grid[0, i] = widgets.VBox(children=(image, button))
display(grid)

本示例使用了 ipywidgets 来构建 GUI，当然也可以使用其他 GUI 框架。

截图：

UI

ipywidgets UI

ImageViewer

一个简单的图片查看器，可以显示多张图片，并可选添加标题。

Solara UI

这些 Solara 组件既可以在 Jupyter Notebook 中使用，也可以嵌入到网页中。

MetadataViewer

用于查看由 ComfyScript / ComfyUI / Stable Diffusion Web UI 生成的图片元数据的组件。同时也支持工作流 JSON 文件，包括 Web UI 格式和 API 格式。

致谢

使用本库的项目

• CarbBot：用于对接 ComfyUI 和/或 Stability AI API，以 SDXL 模型进行文生图的简单 Discord 机器人
• comfy-character-app：基于 ComfyUI 和 ComfyScript 的 Gradio 应用程序，用于通过多步骤流程生成角色。
• io_comfyui：通过 ComfyScript 让 Blender 与 ComfyUI 协同工作。
• Mea comfy wrap：用于将 ComfyUI 工作流封装为微服务，并提供 gRPC 接口的简单脚本
• the-searcher-SD：增强 SDXL 中人物相似度的概念验证工具
• Randomize_ComfyScript：使用 ComfyScript 的 ComfyUI 随机化脚本
• MaLoskins/LineartApp（Flask）

[^graph-gui]: 我讨厌节点。（并非针对 ComfyUI）：StableDiffusion

ComfyScript 快速上手指南

ComfyScript 是 ComfyUI 的 Python 前端和库。它允许你使用可读性强的 Python 代码来定义、运行和生成 ComfyUI 工作流，支持循环、函数调用等编程特性，非常适合开发者进行自动化绘图、工作流复用及 ML 研究。

环境准备

• 操作系统: Windows, Linux, macOS
• Python 版本: >= 3.9 (推荐 3.10+)
• 前置依赖:
  • 方案 A：已安装并运行的 ComfyUI 服务（本地或远程）。
  • 方案 B：完整的 ComfyUI 本地环境（用于作为自定义节点安装）。
  • 可选工具：uv (推荐的快速包管理器)。

国内加速提示：安装 Python 依赖时，建议指定清华或阿里镜像源以提升下载速度。 例如：pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ...

安装步骤

根据你的使用场景，选择以下任一安装方式：

方案一：仅安装 ComfyScript 包（连接现有 ComfyUI 服务）

适用于已有 ComfyUI 服务器（本地或云端），仅需通过 Python 脚本调用的场景。

1. 使用 pip 安装：

   python -m pip install -U "comfy-script[default]" -i https://pypi.tuna.tsinghua.edu.cn/simple
   

2. 或使用 uv 直接运行（无需预先安装环境）：

   uv run examples/uv.py
   

方案二：作为 ComfyUI 自定义节点安装

适用于希望将 ComfyScript 集成到 ComfyUI 界面中，利用其自动转译工作流功能的场景。

1. 进入 ComfyUI 自定义节点目录：

   cd ComfyUI/custom_nodes
   

2. 克隆仓库并安装：

   git clone https://github.com/Chaoses-Ib/ComfyScript.git
   cd ComfyScript
   python -m pip install -e ".[default]" -i https://pypi.tuna.tsinghua.edu.cn/simple
   

   注：[default] 参数用于安装常用依赖，若省略则需手动管理依赖。

方案三：使用 uv 一键搭建完整环境

适用于尚未安装 Python 或 ComfyUI，希望快速构建隔离开发环境的用户。

1. 创建项目目录并初始化虚拟环境：

   mkdir ComfyUI && cd ComfyUI
   uv venv --seed --python 3.12
   

2. 安装 Comfy-Cli 并部署 ComfyUI：

   uv pip install comfy-cli
   uv run comfy --workspace . install
   

3. 安装 ComfyScript：

   git clone https://github.com/Chaoses-Ib/ComfyScript.git ./custom_nodes/ComfyScript
   uv pip install -e "./custom_nodes/ComfyScript[default]"
   

基本使用

以下是最基础的 Python 脚本示例，展示如何加载模型、生成图像并保存。

1. 编写脚本

创建文件 test_comfy.py，写入以下内容：

from comfy_script.runtime import *

# 加载 ComfyUI 服务地址
# 如果是本地默认端口，可简写为 load()
load('http://127.0.0.1:8188/')

from comfy_script.runtime.nodes import *

with Workflow(wait=True):
    # 1. 加载大模型检查点
    model, clip, vae = CheckpointLoaderSimple('v1-5-pruned-emaonly.ckpt')
    
    # 2. 编写提示词
    conditioning = CLIPTextEncode('beautiful scenery nature glass bottle landscape, purple galaxy bottle', clip)
    conditioning2 = CLIPTextEncode('text, watermark', clip)
    
    # 3. 创建潜在空间图像
    latent = EmptyLatentImage(512, 512, 1)
    
    # 4. 采样生成
    latent = KSampler(model, 156680208700286, 20, 8, 'euler', 'normal', conditioning, conditioning2, latent, 1)
    
    # 5. 解码并保存图像
    image = VAEDecode(latent, vae)
    SaveImage(image, 'ComfyUI')
    
    # 提示：若不保存文件而是获取 PIL Image 对象，可使用:
    # images = util.get_images(image)

2. 运行脚本

确保 ComfyUI 服务已在后台运行（默认端口 8188），然后执行：

python test_comfy.py

脚本执行完毕后，生成的图片将保存在 ComfyUI 的输出目录中。你也可以在 Jupyter Notebook 中直接运行上述代码进行交互式开发。