diff --git a/README.md b/README.md index 37aeef87..445a8aa0 100644 --- a/README.md +++ b/README.md @@ -255,6 +255,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` @@ -271,6 +278,38 @@ 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 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 --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 + `--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 @@ -289,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. @@ -298,6 +339,41 @@ 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`, `comfy node reinstall`, + and `comfy node restore-snapshot`. + + `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`, 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 Both flags use `uv` for faster dependency resolution, but they work differently: @@ -305,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+ |