importing-subgraphs

Importing Subgraph Blueprints

Subgraph blueprints are pre-built ComfyUI node components stored in blueprints/ and shipped via the comfyui-subgraph-blueprints package.

Rules

• Never modify scripts, build tooling, or CI configuration.
• Always validate after changes (Step 4).
• Blueprint filenames must be snake_case — the import script handles renaming automatically.
• Use double-quotes " in all JSON files.
• Blueprint JSON must contain a definitions.subgraphs array with at least one entry.

---

Step 1 — Obtain the Blueprint JSON

Two sources:

Option A — Import from an external directory:

python scripts/blueprints/import_blueprints.py --source /path/to/external/blueprints/

The script copies all *.json files (skipping index*.json) into blueprints/, renames them to snake_case, regenerates blueprints/index.json, and updates blueprints_bundles.json.

Option B — Manual placement (single file):

1. Export the subgraph from ComfyUI (Save → Export workflow JSON).
2. Copy the .json file to blueprints/ with a snake_case name, e.g. my_blueprint.json.
3. Run the import script (no --source needed) to normalize and regenerate index + bundles:

   python scripts/blueprints/import_blueprints.py
   

Required blueprint JSON structure

The file must contain definitions.subgraphs[0] with these fields:

Field	Required
name	yes — display name shown in the node palette
inputs	yes — exposed input slots
outputs	yes — exposed output slots
nodes	yes — internal ComfyUI nodes

---

Step 2 — Add a Thumbnail (Optional)

Thumbnail files live in blueprints/ and follow the naming pattern:

{blueprint_name}-1.webp     # primary (required for thumbnail display)
{blueprint_name}-2.webp     # secondary (optional, for compare/hover effects)

• Convert to webp format (lossy ~65% quality).
• The import script sets "mediaSubtype": "webp" in index.json automatically.