Metadata-Version: 2.4
Name: comfy-model-vault
Version: 0.3.0
Summary: Find unused models and broken LoRAs in your ComfyUI install.
Project-URL: Homepage, https://github.com/Chepko932/comfy-vault
Project-URL: Issues, https://github.com/Chepko932/comfy-vault/issues
Author: comfy-vault contributors
License: MIT License
        
        Copyright (c) 2026 Joshua Dormann and comfy-vault contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: civitai,comfyui,lora,model-management,orphan-detection,stable-diffusion
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: pydantic>=2.5
Requires-Dist: pyyaml>=6.0
Provides-Extra: civitai
Requires-Dist: httpx>=0.27; extra == 'civitai'
Provides-Extra: dev
Requires-Dist: fastapi>=0.110; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Requires-Dist: uvicorn>=0.29; extra == 'dev'
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == 'web'
Requires-Dist: uvicorn>=0.29; extra == 'web'
Description-Content-Type: text/markdown

# comfy-vault

Find unused models and broken LoRAs in your ComfyUI install.

`comfy-vault` is a standalone CLI that indexes your `models/` tree (including
nested subfolders), reads your workflow files to see which models you actually
use, and reports the ones nothing references — so you can reclaim disk space
without guessing. It does not need to run inside ComfyUI.

![comfy-vault orphans demo](docs/demo.gif)

## Install

```bash
pip install comfy-model-vault
```

> The PyPI distribution is `comfy-model-vault` (the shorter name was already
> taken); it installs the `comfy-vault` command and the `comfy_vault` package.

Python 3.10+. The only runtime dependencies are `click`, `pydantic` and `pyyaml`.

## Quickstart

```bash
# Index every model under a directory, recursively
comfy-vault scan /path/to/ComfyUI/models

# List models that no workflow references
comfy-vault orphans /path/to/ComfyUI/models \
  --workflows /path/to/ComfyUI/user/default/workflows
```

`orphans` is read-only. To actually remove the files, add `--delete` (it shows
what it will do and asks for confirmation first; `--yes` skips the prompt):

```bash
comfy-vault orphans ./models --workflows ./workflows --delete
```

If your models live in several places, point comfy-vault at your
`extra_model_paths.yaml` and it scans every declared root:

```bash
comfy-vault scan --extra-paths /path/to/extra_model_paths.yaml
```

Find byte-identical duplicates, hash files the way Civitai does, back-fill
Civitai metadata by hash, or pre-flight free space before a download:

```bash
comfy-vault duplicates ./models                 # same-SHA256 copies
comfy-vault hash ./models --cache .vault.json   # SHA256 + Civitai AutoV2
comfy-vault civitai ./models --fixtures ./recorded   # offline metadata back-fill
comfy-vault space /mnt/nas/models --need 6GB    # will the next download fit?
```

## Why

These are real, currently-open behaviours in ComfyUI and its ecosystem that make
manual model cleanup error-prone. comfy-vault works around them from the outside:

- **Models in subfolders are easy to lose track of**
  ([ComfyUI #10711](https://github.com/comfyanonymous/ComfyUI/issues/10711)).
  The scanner walks every level, not just the category root.
- **`extra_model_paths.yaml` parsing is fragile** and can throw on non-string
  values ([ComfyUI #11404](https://github.com/comfyanonymous/ComfyUI/issues/11404),
  [PR #6441](https://github.com/comfyanonymous/ComfyUI/pull/6441) closed
  unmerged). comfy-vault's parser skips reserved keys and bad values instead of
  crashing.
- **Symlinks and junctions break on update**, especially on Windows
  ([ComfyUI #7662](https://github.com/comfyanonymous/ComfyUI/issues/7662),
  [#4412](https://github.com/comfyanonymous/ComfyUI/issues/4412)). comfy-vault
  reads canonical paths and never relies on ComfyUI-managed links.

There is no widely-used standalone orphan detector for ComfyUI today, which is
the gap this fills.

## Comparison

comfy-vault is not a replacement for the model managers — it does one thing they
don't, and skips the things they do well.

| | comfy-vault | ComfyUI-Manager | ComfyUI-Lora-Manager |
|---|---|---|---|
| Runs without ComfyUI | yes | no (extension) | no (extension) |
| Recursive subfolder scan | yes | partial | yes |
| Orphan detection from workflows | yes | no | no |
| Duplicate detection (content hash) | yes | no | metadata-based |
| Civitai metadata back-fill (by hash) | yes | no | yes |
| Download / install models | no | yes | yes |
| In-ComfyUI UI | no | yes | yes |

If you want to download models or manage them inside the ComfyUI web UI, use the
managers above. Use comfy-vault when you want to find and remove what you no
longer need, or to audit a large library from a script or a backup host.

## How orphan detection decides

A model is an orphan when no scanned workflow references its filename. Reference
extraction is intentionally greedy: any string in a workflow JSON that ends in a
known model extension counts as "in use", across both the UI and API workflow
formats and any custom node. Because `--delete` removes files, comfy-vault errs
toward keeping a model rather than risk flagging one that is actually used.
Deletion is also confined to files inside the directories you scanned.

## How duplicate detection avoids false positives

`comfy-vault duplicates` groups files only by their full SHA256, so two files
are duplicates **iff their bytes are identical**. Four distinct LoRAs that share
a name or a Civitai model are never grouped, because their content differs —
which is exactly the false positive reported in
[Lora-Manager #841](https://github.com/willmiao/ComfyUI-Lora-Manager/issues/841),
where weaker matching flagged four different Qwen LoRAs as duplicates.

## Web UI

For a read-only browser view, install the web extra and run the server:

```bash
pip install "comfy-model-vault[web]"
comfy-vault serve --models-dir /path/to/ComfyUI/models \
  --workflows /path/to/ComfyUI/user/default/workflows
```

It serves on `http://127.0.0.1:8200` (FastAPI + HTMX, no JS framework) with an
overview, the orphan and duplicate lists, base-model mismatch warnings, and a
Civitai version browser. The base-model warnings flag LoRAs whose Civitai base
model is not covered by any installed checkpoint; the version browser lists every
Civitai version of a model and marks which are installed
([Lora-Manager #778](https://github.com/willmiao/ComfyUI-Lora-Manager/issues/778)).

## License

[MIT](LICENSE).
