Getting Started

Prerequisites

Requirement	Notes
Python 3.10+	Checked at install time
A running ComfyUI	Comfy Headless is a client — it does not render anything itself
Ollama (optional)	Only for AI prompt enhancement

Start ComfyUI first and note its address. The default assumption is http://localhost:8188.

Install

pip install comfy-headless[standard]

[standard] is the right default for most people: it adds AI prompt enhancement and WebSocket progress on top of the core client.

If you want the smallest possible footprint:

pip install comfy-headless          # core only, ~2MB

Or everything, including the web UI:

pip install comfy-headless[full]

See Configuration for the full extras table.

Verify the install

comfy-headless --version
comfy-headless --check       # which optional features are active
comfy-headless --diagnose    # version, Python, features, resolved config

--diagnose is the fastest way to answer “why isn’t this working” — it prints the resolved ComfyUI URL alongside feature availability.

Your first image

from comfy_headless import ComfyClient

client = ComfyClient()                  # http://localhost:8188
result = client.generate_image("a beautiful sunset over mountains")

print(result["success"])                # True
print(result["images"])                 # list of output paths
print(result["seed"])                   # the seed actually used

Every generation call returns a dict, not a result object. The keys are success, prompt_id, images (or videos), error, seed and preset.

Pointing at a different server

client = ComfyClient("http://192.168.1.50:8188")

Or set it in the environment, which is usually better for anything scripted:

export COMFY_HEADLESS_COMFYUI__URL=http://192.168.1.50:8188

Note the __ double underscore — it separates the config section from the key. See Configuration.

Check the server is reachable

if not client.is_online():
    raise SystemExit("ComfyUI is not responding")

print(client.get_vram_gb(), "GB total VRAM")
print(client.get_free_vram_gb(), "GB free")

client.ensure_online() does the same thing but raises ComfyUIOfflineError instead of returning a boolean.

Use a preset

Presets set resolution, steps and CFG together, and override any individual values you also pass:

result = client.generate_image("a mountain lake at dawn", preset="hd")

Available: draft, fast, quality, hd, portrait, landscape, cinematic, square.

from comfy_headless import list_presets
print(list_presets())

Your first video

result = client.generate_video(
    "a slow pan across a mountain range",
    preset="ltx_quality",
)
print(result["videos"])

Video is selected by preset, not by model name — there is no model argument. If you are unsure which preset your GPU can handle:

from comfy_headless import get_recommended_preset
print(get_recommended_preset(vram_gb=16))

See Video Models for the full list and what each family needs.

Your first mesh, track, and caption

The same client covers the other profiles — every call returns the same dict shape, and get_file() fetches any output type:

# 3D: image in, GLB out (all core nodes)
result = client.generate_3d("character.png")
open("character.glb", "wb").write(client.get_file(**result["meshes"][0]))

# Audio: text-to-music (all core nodes, MIT weights)
result = client.generate_audio(tags="lo-fi, jazz, mellow", seconds=30)
open("track.flac", "wb").write(client.get_file(**result["audios"][0]))

# Inference: ask about an image (needs the comfyui-florence2 pack)
result = client.run_inference("photo.png", task="caption")
print(result["text"])

See The Six Profiles for what each profile can do and which (few) need custom node packs.

Before you spend a long run

Video graphs can require custom node packs. Ask first rather than discovering it at submit time:

workflow = client.build_video_workflow("a cat walking")

report = client.check_workflow_dependencies(workflow)
if report["missing_packs"]:
    print("Install these first:", report["missing_packs"])

Troubleshooting

Symptom	Likely cause
ComfyUIOfflineError	ComfyUI isn’t running, or the URL is wrong — check --diagnose
MissingNodePackError	The graph needs a custom node pack this server doesn’t have
GenerationTimeoutError	Model still loading, or the job is genuinely slow — raise timeout
AI functions missing	Install [ai] and start Ollama
Import error on launch	Install [ui]

Next

• Usage — the day-to-day API
• For Beginners — a gentler introduction if the above moved too fast