Save Checkpoint with Metadata

ComfyUI-SaveCheckpointWithMetadata

Save .safetensors files with custom metadata and explicit filename behavior in ComfyUI.

This extension provides two nodes:

• Save Checkpoint with Metadata - saves a checkpoint-style .safetensors file from MODEL, with optional CLIP, VAE, and CLIP_VISION inputs.
• Save Diffusion Model with Metadata - saves only a MODEL / diffusion-model-style .safetensors file, without CLIP, VAE, or CLIP_VISION inputs.

Both nodes share the same metadata control and filename behavior:

• Write exactly the header you want via metadata_json.
• Optional prompt_override to replace the hidden PROMPT.
• Merge mode to include hidden EXTRA_PNGINFO.
• Filename modes:
  • smart_counter: first save uses unsuffixed prefix.safetensors if free, next saves continue from the next free counter without going backwards.
  • no_counter_overwrite: always write to prefix.safetensors and overwrite if it exists.

Install

ComfyUI Manager

1. Manager -> Install via Git URL -> paste:

https://github.com/a-l-e-x-d-s-9/ComfyUI-SaveCheckpointWithMetadata.git

2. Restart ComfyUI.

If Manager shows a security level error, either install manually or add the repo to the Manager catalog. See Troubleshooting below.

Manual

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/a-l-e-x-d-s-9/ComfyUI-SaveCheckpointWithMetadata.git

# optional deps
python3 -m pip install -r ComfyUI-SaveCheckpointWithMetadata/requirements.txt

# optional post-install hook
python3 ComfyUI-SaveCheckpointWithMetadata/install.py || true

Restart ComfyUI.

Node location

• Category: advanced/model_merging
• Display names:
  • Save Checkpoint with Metadata
  • Save Diffusion Model with Metadata

Which node should I use?

Use Save Checkpoint with Metadata when:

• You want to save a checkpoint-style file.
• You want optional CLIP, VAE, or CLIP_VISION saved into the file.
• You want the default prefix to point to checkpoints/CustomMeta.

Use Save Diffusion Model with Metadata when:

• You want a model-only file similar in purpose to ComfyUI's built-in ModelSave node.
• You only want to provide a single MODEL input.
• You do not want CLIP, VAE, or CLIP_VISION inputs on the node.
• You want the default prefix to point to diffusion_models/CustomMeta.

Quick start - checkpoint save

1. Add Save Checkpoint with Metadata.
2. Wire your MODEL into the node.
3. Optionally wire CLIP, VAE, and/or CLIP_VISION.
4. Choose filename_prefix, for example checkpoints/MyModel.
5. Pick filename_mode:
   • smart_counter for automatic unique names.
   • no_counter_overwrite to always write prefix.safetensors.
6. Pick metadata_mode:
   • replace to write only your metadata_json.
   • merge_minimal to start with prompt plus optional EXTRA_PNGINFO, then apply metadata_json.
7. Fill metadata_json with a JSON object of header keys.
8. Optionally set prompt_override to replace the hidden PROMPT in merge mode.
9. Queue. Your checkpoint is saved in ComfyUI's output directory under the resolved subfolder.

Quick start - diffusion model save

1. Add Save Diffusion Model with Metadata.
2. Wire your MODEL into the node.
3. Choose filename_prefix, for example diffusion_models/MyModel.
4. Pick filename_mode:
   • smart_counter for automatic unique names.
   • no_counter_overwrite to always write prefix.safetensors.
5. Pick metadata_mode:
   • replace to write only your metadata_json.
   • merge_minimal to start with prompt plus optional EXTRA_PNGINFO, then apply metadata_json.
6. Fill metadata_json with a JSON object of header keys.
7. Optionally set prompt_override to replace the hidden PROMPT in merge mode.
8. Queue. Your model file is saved in ComfyUI's output directory under the resolved subfolder.

Inputs

Shared inputs

Both nodes have these inputs:

| Input | Type | Description | |------|------|-------------| | model | MODEL | The model to serialize into a .safetensors file. | | filename_prefix | STRING | Subfolder and base name under ComfyUI output directory, for example checkpoints/MyModel or diffusion_models/MyModel. | | filename_mode | DROPDOWN | smart_counter or no_counter_overwrite. See Filename behavior. | | metadata_json | STRING (multiline) | JSON object of header keys to write. Values must be strings; non-strings are JSON-encoded for you. Example: {"author":"Alex","training":{"epochs":80}}. | | metadata_mode | DROPDOWN | replace: write only metadata_json. merge_minimal: base header includes prompt and, optionally, EXTRA_PNGINFO, then your metadata_json overwrites or adds keys. | | include_extra_pnginfo | BOOLEAN | Used only in merge_minimal. When on, copy keys from hidden EXTRA_PNGINFO into the base header. | | prompt_override | STRING (multiline) | Optional override for the hidden PROMPT. Ignored in replace. In merge_minimal, becomes the base prompt unless you also set prompt in metadata_json. |

Extra inputs on Save Checkpoint with Metadata

Only Save Checkpoint with Metadata has these optional inputs:

| Input | Type | Description | |------|------|-------------| | clip | CLIP (optional) | Embed CLIP in the checkpoint. | | vae | VAE (optional) | Embed VAE in the checkpoint. | | clip_vision | CLIP_VISION (optional) | Embed CLIP_VISION in the checkpoint. |

Save Diffusion Model with Metadata intentionally does not expose these inputs.

Tip: To see tooltips, enable ComfyUI Settings -> Nodes -> Enable Tooltips.

Outputs

Both nodes output text values so you can inspect what was written:

| Output | Description | |--------|-------------| | saved path | Full path to the saved .safetensors file. Named ckpt_path on the checkpoint node and model_path on the diffusion model node. | | saved_metadata | Final metadata dictionary written to the safetensors header, formatted as JSON. | | saved_prompt | The final prompt metadata value, if present. | | saved_extra_pnginfo | The subset of EXTRA_PNGINFO copied into metadata when using merge_minimal. |

Filename behavior

smart_counter

• If prefix.safetensors does not exist, write there.
• Otherwise continue with prefix_00001_.safetensors, prefix_00002_.safetensors, etc.
• The node scans existing files and uses the next free suffix.

no_counter_overwrite

• Always write to prefix.safetensors.
• If the file exists, it is overwritten.

Metadata behavior

replace

The final safetensors header contains only the keys from metadata_json.

prompt_override, hidden PROMPT, and hidden EXTRA_PNGINFO are ignored.

merge_minimal

The node builds a small base metadata dictionary first:

1. Adds prompt from prompt_override, if provided.
2. Otherwise adds prompt from hidden ComfyUI PROMPT, if available.
3. Adds hidden EXTRA_PNGINFO keys if include_extra_pnginfo is enabled.
4. Applies metadata_json last.

Keys in metadata_json win over keys from the base metadata.

Examples

Replace-only header

• metadata_mode: replace
• metadata_json:

{"author":"author","project":"Flux-Kontext","modelspec.architecture":"sdxl"}

Result: header contains exactly those keys.

Merge prompt and extra info, then override

• metadata_mode: merge_minimal
• prompt_override: paste your workflow JSON or plain text
• include_extra_pnginfo: on
• metadata_json:

{"prompt":"OVERRIDE","author":"Alex","training":{"epochs":80}}

Result: the final prompt value is OVERRIDE, because metadata_json is applied last.

Save a model-only file

Use Save Diffusion Model with Metadata with:

• filename_prefix: diffusion_models/MyModel
• metadata_mode: replace
• metadata_json:

{"author":"Alex","model_type":"diffusion_model","modelspec.architecture":"flux"}

Notes

• Safetensors metadata requires dict[str, str]. Non-string values are JSON-encoded by the node.
• These nodes do not follow the stock --disable-metadata flag. They write the metadata you specify.
• Hidden inputs PROMPT and EXTRA_PNGINFO are provided by ComfyUI runtime. The nodes only read them when merge_minimal is selected.
• Save Diffusion Model with Metadata saves only the MODEL object and ignores CLIP/VAE/CLIP_VISION by design.
• For maximum compatibility, test the output of Save Diffusion Model with Metadata by loading it through the same ComfyUI loader you normally use for diffusion model files.

Troubleshooting

Manager shows: This action is not allowed with this security level configuration.

• Option A: Manual install by git clone into ComfyUI/custom_nodes/.
• Option B: Lower Manager security_level to middle or weak in its config.ini, then restart ComfyUI.
• Option C: Submit your repo to the ComfyUI-Manager catalog (custom-node-list.json) so it can be installed at normal security. Until the PR is merged, users can use Install via Git URL or manual install.

I see prefix_00001_.safetensors even on the first save

In smart_counter, the node prefers prefix.safetensors if it does not exist. If you still get a numbered file, check that a file named prefix.safetensors is not already present in the resolved output folder.

I want modelspec.* keys like the stock node adds

Add them to metadata_json explicitly. Example:

{"modelspec.architecture":"sdxl","modelspec.vision":"clip"}

The diffusion model file does not load where I expected

Save Diffusion Model with Metadata is intended for model-only saves, but exact compatibility can depend on the model type and the loader you use later. Try loading the output with the same ComfyUI model-only loader you normally use. If you need full checkpoint behavior with CLIP/VAE included, use Save Checkpoint with Metadata instead.

License

No.

Credits

Author: alexds9

Inspired by ComfyUI stock saving logic, with explicit metadata and naming control.