From 7f679cdf8712cd479f09eefb091d8d2ec2b28215 Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Thu, 23 Jul 2026 22:22:53 -0700 Subject: [PATCH 1/2] docs: document registry-install & --fast-deps, clarify node-install example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add README documentation for the two custom-node install paths (comfy node install vs registry-install), document the --fast-deps flag (which commands accept it and why registry-install does not), and add a note explaining that node-install arguments are lowercase Comfy Registry IDs — the source of the 'Node "ComfyUI-Impact-Pack@unknown" not found' error reported in #257. Closes #257 --- README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/README.md b/README.md index 074e1408..aece276a 100644 --- a/README.md +++ b/README.md @@ -226,6 +226,13 @@ comfy node [show|simple-show] [installed|enabled|not-installed|disabled|all|snap `comfy node install comfyui-impact-pack` + > **Note:** the argument is the node's **Comfy Registry ID**, which is + > lowercase (e.g. `comfyui-impact-pack`), not the GitHub repository name + > (`ComfyUI-Impact-Pack`). Passing the repo-name casing fails to resolve with + > an error like `Node 'ComfyUI-Impact-Pack@unknown' not found`. Find a node's + > ID on its [Comfy Registry](https://registry.comfy.org) page or via + > `comfy node show all`. + - Managing snapshot: `comfy node save-snapshot` @@ -242,6 +249,39 @@ comfy node [show|simple-show] [installed|enabled|not-installed|disabled|all|snap `comfy node deps-in-workflow --workflow= --output=` +#### `install` vs `registry-install` + +comfy-cli offers two ways to install a custom node, backed by different +mechanisms: + +- **`comfy node install ...`** delegates to + [ComfyUI-Manager](https://github.com/Comfy-Org/ComfyUI-Manager)'s `cm-cli`. + It accepts one or more node IDs, resolves them through the Manager's channel + database (`--channel`, `--mode`), and installs dependencies via the Manager + (so it also supports `--fast-deps`, `--no-deps`, and `--uv-compile`). This is + the recommended command for day-to-day node management, and it requires + ComfyUI-Manager to be present in the workspace. + + `comfy node install comfyui-impact-pack` + +- **`comfy node registry-install [version]`** talks directly to the + [Comfy Registry](https://registry.comfy.org) API. It downloads the published + archive for a single node (optionally pinned to a specific `version`), + extracts it into `custom_nodes/`, and runs the node's own install script. It + does **not** go through ComfyUI-Manager, so it does not require the Manager to + be installed — this is the command the Registry's own install instructions + use. + + `comfy node registry-install comfyui-impact-pack` + + `comfy node registry-install comfyui-impact-pack 1.0.0` # install a specific version + + Because `registry-install` bypasses the Manager's dependency machinery and + simply runs the node's bundled install script, it only accepts + `--force-download` — it does **not** accept `--fast-deps`, `--no-deps`, or + `--uv-compile`. If you want fast/unified dependency resolution, use + `comfy node install` instead. + #### Unified Dependency Resolution (--uv-compile) Requires ComfyUI-Manager v4.1+. Instead of installing dependencies per-node with @@ -269,6 +309,26 @@ it can identify which node packs have incompatible dependencies and why. `comfy node install comfyui-impact-pack --no-uv-compile` +#### --fast-deps + +`--fast-deps` swaps comfy-cli's dependency installation from `pip` to comfy-cli's +built-in `uv`-based resolver (`DependencyCompiler`), which is significantly +faster and only requires `uv` (no ComfyUI-Manager). On a dependency version +conflict it prompts you interactively to pick a version. + +- Accepted by: `comfy install`, `comfy node install`, and + `comfy node reinstall`. + + `comfy install --fast-deps` + + `comfy node install comfyui-impact-pack --fast-deps` + +- **Not** accepted by `comfy node registry-install`: that command installs a + node directly from the Comfy Registry by running the node's own bundled + install script, so it never touches comfy-cli's dependency resolver (see + [`install` vs `registry-install`](#install-vs-registry-install) above). +- Mutually exclusive with `--no-deps` and `--uv-compile`. + #### --fast-deps vs --uv-compile Both flags use `uv` for faster dependency resolution, but they work differently: From f63d8aa9ca2862845b215b177e6dbc48d3ce14ba Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Thu, 30 Jul 2026 01:00:32 -0700 Subject: [PATCH 2/2] docs: fix registry-install --version syntax, add restore-snapshot to --fast-deps (BE-4275) Addresses review on #587: - `comfy node registry-install [version]` documented a positional version, but typer renders the defaulted `version: str | None` as the `--version` option. The example errored with exit 2 ("Got unexpected extra argument (1.0.0)"). Fixed the section signature and the example to use `--version 1.0.0`. - #589 landed `--fast-deps` on `comfy node restore-snapshot`, so the "Accepted by" list and the comparison table's Scope row were stale. Added it, and documented that restore-snapshot is an exception to the blanket "mutually exclusive with --no-deps and --uv-compile" claim: there `--fast-deps` *selects* the uv-compile fast path (cm_cli has no --no-deps on that subcommand and its --uv-compile implies no-deps), and it is `--fast-deps --no-uv-compile` that errors. Every flag claim verified against the live CLI via --help and by invoking the rejected combinations. --- README.md | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index e260be3b..445a8aa0 100644 --- a/README.md +++ b/README.md @@ -293,17 +293,16 @@ mechanisms: `comfy node install comfyui-impact-pack` -- **`comfy node registry-install [version]`** talks directly to the +- **`comfy node registry-install [--version ]`** talks directly to the [Comfy Registry](https://registry.comfy.org) API. It downloads the published - archive for a single node (optionally pinned to a specific `version`), - extracts it into `custom_nodes/`, and runs the node's own install script. It - does **not** go through ComfyUI-Manager, so it does not require the Manager to - be installed — this is the command the Registry's own install instructions - use. + archive for a single node (optionally pinned with `--version`), extracts it + into `custom_nodes/`, and runs the node's own install script. It does **not** + go through ComfyUI-Manager, so it does not require the Manager to be + installed — this is the command the Registry's own install instructions use. `comfy node registry-install comfyui-impact-pack` - `comfy node registry-install comfyui-impact-pack 1.0.0` # install a specific version + `comfy node registry-install comfyui-impact-pack --version 1.0.0` # install a specific version Because `registry-install` bypasses the Manager's dependency machinery and simply runs the node's bundled install script, it only accepts @@ -329,7 +328,9 @@ it can identify which node packs have incompatible dependencies and why. `comfy node uv-sync` -- `--uv-compile` is mutually exclusive with `--fast-deps` and `--no-deps`. +- `--uv-compile` is mutually exclusive with `--fast-deps` and `--no-deps` — + except on `restore-snapshot`, where `--fast-deps` selects the `--uv-compile` + path instead (see [--fast-deps](#--fast-deps) below). - To make `--uv-compile` the default for all commands, see [uv-compile default](#uv-compile-default) below. @@ -345,8 +346,8 @@ built-in `uv`-based resolver (`DependencyCompiler`), which is significantly faster and only requires `uv` (no ComfyUI-Manager). On a dependency version conflict it prompts you interactively to pick a version. -- Accepted by: `comfy install`, `comfy node install`, and - `comfy node reinstall`. +- Accepted by: `comfy install`, `comfy node install`, `comfy node reinstall`, + and `comfy node restore-snapshot`. `comfy install --fast-deps` @@ -356,7 +357,22 @@ conflict it prompts you interactively to pick a version. node directly from the Comfy Registry by running the node's own bundled install script, so it never touches comfy-cli's dependency resolver (see [`install` vs `registry-install`](#install-vs-registry-install) above). -- Mutually exclusive with `--no-deps` and `--uv-compile`. +- Mutually exclusive with `--no-deps` and `--uv-compile`, where those flags + exist — the exact pairing is per-command: + + | Command | Rejected combination | + |---------|----------------------| + | `comfy node install` | `--fast-deps --no-deps`, `--fast-deps --uv-compile` | + | `comfy node reinstall` | `--fast-deps --uv-compile` (no `--no-deps` on this command) | + | `comfy node restore-snapshot` | `--fast-deps --no-uv-compile` (see below) | + | `comfy install` | none (neither flag exists on this command) | + +- **Exception — `comfy node restore-snapshot`:** here `--fast-deps` *selects* + the `--uv-compile` fast path rather than conflicting with it. ComfyUI-Manager's + `cm-cli` has no `--no-deps` on `restore-snapshot`, and its `--uv-compile` + already implies no-deps internally, so the two are synonyms on this command. + Combining `--fast-deps` with `--no-uv-compile` is the contradiction, and it + errors: `Cannot use --fast-deps with --no-uv-compile`. #### --fast-deps vs --uv-compile @@ -365,7 +381,7 @@ Both flags use `uv` for faster dependency resolution, but they work differently: | | `--fast-deps` | `--uv-compile` | |-----------------------|-------------------------------------------------|-----------------------------------------------| | **Resolver** | comfy-cli built-in (`DependencyCompiler`) | ComfyUI-Manager (`UnifiedDepResolver`) | -| **Scope** | `comfy install`, `comfy node install/reinstall` | Custom node commands only | +| **Scope** | `comfy install`, `comfy node install/reinstall/restore-snapshot` | Custom node commands only | | **Conflict handling** | Interactive prompt to pick a version | Automatic detection with node attribution | | **Config default** | No | Yes (`comfy manager uv-compile-default true`) | | **Requires** | Only `uv` | ComfyUI-Manager v4.1+ |