# ComfyScript: a Python frontend for ComfyUI workflows

> ComfyScript turns ComfyUI graphs into Python you can read, run and generate. It is a good fit for people who want loops and library calls around diffusion nodes, and a poor fit for anyone who only wants a GUI.

**Chaoses-Ib/ComfyScript** — A Python frontend and library for ComfyUI

- Repository: https://github.com/Chaoses-Ib/ComfyScript
- Website: https://discord.gg/arqJbtEg7w
- Stars: 705 · Forks: 47
- Language: Python
- License: MIT
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/chaoses-ib-comfyscript

## What ComfyScript is for, and who it is not for

ComfyUI stores a workflow as a JSON graph. That format is machine-friendly and human-hostile: node identifiers, widget positions and link arrays make a diff between two versions of a workflow close to unreadable, and there is no natural place to put a loop. ComfyScript's stated purpose is to act as a human-readable format for those workflows, so that parts of one can be compared and reused. The README also notes that many LLMs handle Python reasonably well, which makes a Python representation a better target for generated workflows than raw graph JSON.

The second use case is execution. Running a script directly means Python control flow sits next to ComfyUI nodes: loops, calls into ordinary libraries, and wrappers around custom nodes. The README frames this as a trade-off against the web UI, and it is one. If your work is mostly dragging nodes and adjusting a few values, the graph editor wins. ComfyScript pays off when the workflow itself is the thing you are computing, or when the same graph has to run inside a larger program.

A third case is using ComfyUI as a function library. Nodes become callable functions, which the README suggests for ML research, reusing nodes in other projects, debugging custom nodes, and caching optimisation. That is a different audience from the image-generation hobbyist: it is someone writing Python who happens to need a diffusion sampler.

## How a script becomes a running ComfyUI graph

The runtime is the part that matters. A script calls load() with either a ComfyUI server URL or a local path, then imports comfy_script.runtime.nodes, which exposes the nodes as Python callables. Node calls are recorded rather than executed immediately, and a Workflow context manager decides when the recorded graph is sent.

The README's first example uses Workflow(wait=True), which means the script blocks until the server finishes. Inside that block, EmptyImage() produces an image tensor and util.get_images(image, save=True) retrieves and writes it. The wait flag is the boundary between building a graph and running it, which is why the same code can also be used to generate a workflow without executing anything.

The README lists several modes under the runtime documentation: real mode for using nodes as functions, workflow generation for producing graphs to use elsewhere, workflow information retrieval by running a script against stubs, and conversion from ComfyUI's web UI format to API format without opening the web UI. The transpiler is the reverse direction: it takes an existing ComfyUI workflow and translates it into a ComfyScript script, using networkx to walk the graph and dynaconf for configuration, and it also needs node information from a ComfyUI instance. That dependency on a live or reachable ComfyUI is worth noting, because it means the transpiler is not a standalone offline converter for arbitrary workflow files.

## Installing comfy-script and running a first workflow

There are three installation paths in the README, and they differ in what you already have. If you only want the package and will point it at a ComfyUI server, install it with pip and use the [default] extra, which the README says is necessary to pull in the common dependencies. Without an extra, ComfyScript installs with no dependencies at all.

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

The README's test script loads a server URL, imports the node namespace, and runs one node inside a waiting workflow. Save it as examples/runtime.py and run it with python; the expected result is a saved image produced by the server at the address you passed to load().

```python
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)
```

If you have ComfyUI installed already, the README clones the repository into ComfyUI/custom_nodes and installs it in editable mode from there, which is the layout ComfyUI expects for custom nodes:

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

The third path uses uv to create a Python 3.12 virtual environment, install Comfy-Cli and ComfyUI, then install ComfyScript into ./custom_nodes/ComfyScript. The README warns that uv only discovers the ComfyUI venv when the working directory is ComfyUI or a directory directly under it, so from ComfyUI/custom_nodes/ComfyScript or from your own script directory you have to activate the venv yourself with .venv\Scripts\activate on Windows or source .venv/bin/activate on Linux. Updating is a git pull followed by the same editable install command.

## Where ComfyScript gets in the way

The dependency extras are the first practical constraint. The package declares no mandatory dependencies, and the default extra pulls in a chain: client, transpile, runtime, nodes, cli and jupyter. The nodes extra installs three specific custom node packages (ComfyUI_Ib_CustomNodes, comfyui-tooling-nodes and civitai_comfy_nodes). If you install with [default] and never use those nodes, you are carrying them anyway. If you install with no extra, you get a package that cannot talk to a server until you add the pieces yourself.

The runtime also assumes ComfyUI is reachable. The README's examples load either a URL or a local path, and the transpiler needs node information from ComfyUI. There is no documented path for transpiling a workflow file in isolation on a machine with no ComfyUI installation, so if your goal is to convert graphs inside a CI container, plan for provisioning ComfyUI there.

Version compatibility is the other soft spot. The project pins requires-python to >=3.9, while the pyproject comments note that ComfyUI itself is >=3.8 and the comfyui pip package is >=3.9. The node namespace is generated from what the connected instance reports, so a script written against one set of custom nodes will not necessarily resolve against another. The README's own documentation set includes a node compatibility page, which is a signal that this is a known area rather than a solved one. Finally, the most recent release listed is v0.7.0a1, an alpha, with v0.6.1 as the stable version before it. The last push to the repository was on 2026-07-18.

## ComfyUI-to-Python-Extension and the difference in approach

The README devotes a documentation page to the differences from ComfyUI-to-Python-Extension, which is the closest comparison. Both take a ComfyUI workflow and produce Python, but they sit at different points in the process.

ComfyUI-to-Python-Extension converts an exported workflow into a standalone script that talks to the ComfyUI API. The output is a one-shot translation: you get a file, you run it, and it does the thing the graph did. ComfyScript keeps a live connection to ComfyUI and exposes its nodes as Python objects that you call as you write the script. That difference shows up in what you can do afterwards. With ComfyScript you can call util.get_images to pull results back into Python, run the same script against a local path instead of a server, or use the runtime in real mode to treat nodes as library functions in a larger program. With a generated standalone script, iterating means regenerating from the graph.

Neither approach is strictly better. A generated script has no runtime dependency on ComfyScript and is easy to hand to someone else. ComfyScript's scripts depend on the package and on a reachable ComfyUI, and in exchange they can loop, branch and compose with other Python code.

## Conclusion

Adopt ComfyScript if you already run ComfyUI and want workflows expressed as Python you can diff, loop over and import from other code. Do not adopt it if you have no ComfyUI instance, or if a graph editor is how you prefer to work and you have no need for programmatic control. Before committing, verify that the node names your workflow uses resolve under the version of ComfyUI you run, and check whether the transpiler output for your own graph is something you would want to maintain.

## FAQ

### What is ComfyScript used for?

The README lists several uses: a human-readable format for ComfyUI workflows, running scripts directly to generate images, using ComfyUI nodes as a function library, generating workflows with scripts, retrieving workflow information through stubs, and converting web UI workflows to API format. It is a Python frontend and library for ComfyUI.

### How do I install ComfyScript?

For use with an external ComfyUI server, the README gives python -m pip install -U "comfy-script[default]". To install it alongside ComfyUI, clone the repository into ComfyUI/custom_nodes and run python -m pip install -e ".[default]" from the ComfyScript directory.

### Does ComfyScript need a running ComfyUI instance?

The README's runtime examples call load() with either a server URL such as http://127.0.0.1:8188/ or a local ComfyUI path, and the transpiler needs node information from ComfyUI. There is no documented offline-only mode for converting arbitrary workflow files.

## Sources

- [Chaoses-Ib/ComfyScript on GitHub](https://github.com/Chaoses-Ib/ComfyScript)
- [License: MIT](https://github.com/Chaoses-Ib/ComfyScript/blob/main/LICENSE)
- [Project website](https://discord.gg/arqJbtEg7w)
- [README](https://github.com/Chaoses-Ib/ComfyScript/blob/main/README.md)
- [Releases](https://github.com/Chaoses-Ib/ComfyScript/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/chaoses-ib-comfyscript