ComfyUI-SaveCheckpointWithMetadata

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

• 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 your 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 name: Save Checkpoint with Metadata

Quick start

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

Inputs

Input	Type	Description
model	MODEL	The model to serialize into a .safetensors checkpoint.
filename_prefix	STRING	Subfolder and base name under ComfyUI output directory, for example checkpoints/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.
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.

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

Filename behavior

• smart_counter

  • If prefix.safetensors does not exist, write there.
  • Otherwise continue with prefix_00001_.safetensors, prefix_00002_.safetensors, etc., starting from the next free index. If ComfyUI hints a large counter, we do not go backwards; we probe from hint+1 upward.

• no_counter_overwrite

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

Examples

Replace-only header

• metadata_mode: replace
• metadata_json:

{"author":"AIxFun eStudio","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}}

Notes

• Safetensors metadata requires dict[str, str]. Non-strings are JSON-encoded by the node.
• This node does not follow the stock --disable-metadata flag. It writes exactly what you specify.
• Hidden inputs PROMPT and EXTRA_PNGINFO are provided by ComfyUI runtime. The node only reads them when merge_minimal is selected.

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 we prefer prefix.safetensors if it does not exist. If you still get a numbered file, ensure the output directory exists and that no file named prefix.safetensors is present.

I want modelspec.* keys like the stock node adds

• Add them to metadata_json explicitly. Example:

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

License

No.

Credits

Author: alexds9 Inspired by ComfyUI stock saving logic but with explicit metadata and naming control.