Updated README for consistency and clarity.#12636
Updated README for consistency and clarity.#12636c0dezer019 wants to merge 7 commits intoComfy-Org:masterfrom
Conversation
- Also updated CLI and installation instructions for those unfamiliar with Python
c0dezer019
requested review from
Kosinkadink,
comfyanonymous and
guill
as code owners
📝 WalkthroughWalkthroughThis PR restructures README.md: replaces multiple "Get Started" bullets with a single options table; adds an Examples link section and relocates related content; consolidates model lists under bolded category headings (Image, Video, Audio, 3D, etc.); expands/rewords sections on asynchronous queueing, memory offloading, TLS, and loading/embeddings; condenses installation and usage into table/enumerated formats; revises Shortcuts/Keybinds; reorganizes Release Process and repo descriptions; simplifies running/troubleshooting instructions; and standardizes punctuation, capitalization, and phrasing. 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
README.md (1)
392-392: Keep section heading levels consistent (##instead of extra#).These new headings become top-level H1s mid-document, which weakens README structure and TOC navigation.
As per coding guidelines, "Only comment on issues directly introduced by this PR's code changes."
Also applies to: 421-421, 501-501
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` at line 392, Change any unintended top-level H1 headings introduced by this PR in README.md (e.g., the "Running" heading shown) to second-level headings so document structure stays consistent — replace "# Running" with "## Running" and do the same for the other similar headings noted in this PR (the other two occurrences flagged) to restore proper heading hierarchy and TOC behavior.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Around line 201-203: The README currently only shows the POSIX activation
command "source venv/bin/activate"; update both occurrences to include the
equivalent Windows activation instructions as well (PowerShell and CMD/Batch),
referencing the venv Scripts folder (e.g., the PowerShell Activate.ps1 and the
CMD/activate.bat variants) so Windows users can activate the virtualenv; ensure
the Windows lines appear alongside the POSIX line and mirror the surrounding
installation steps.
---
Nitpick comments:
In `@README.md`:
- Line 392: Change any unintended top-level H1 headings introduced by this PR in
README.md (e.g., the "Running" heading shown) to second-level headings so
document structure stays consistent — replace "# Running" with "## Running" and
do the same for the other similar headings noted in this PR (the other two
occurrences flagged) to restore proper heading hierarchy and TOC behavior.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5be2af5545
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- Added venv activation instructions for windows users alongside POSIX instructions
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (2)
README.md (2)
230-239: Windows venv activation parity here too — LGTM.The manual-install block mirrors the comfy-cli block with all three activation variants. Consistent and correct.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 230 - 239, This README venv activation block (the fenced code block starting with "python -m venv venv" and containing the Linux/macOS, Windows (PowerShell), and Windows (CMD) activation lines) is correct and mirrors the comfy-cli section — no code changes required; leave this block as-is and remove any duplicate review tags like "[duplicate_comment]" from the PR metadata if present.
199-216: Windows venv activation is now properly addressed — LGTM.Both PowerShell (
Activate.ps1) and CMD (activate.bat) activation paths are now documented alongside the POSIX instruction. The past review concern is resolved.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 199 - 216, The PR contains a duplicated reviewer note (duplicate_comment) while the README's virtualenv activation block already correctly includes both PowerShell (Activate.ps1) and CMD (activate.bat) instructions; remove the redundant duplicate review comment/marker from the PR so there’s a single approval and leave the README activation code block (the lines mentioning Activate.ps1 and activate.bat) as-is to retain Windows activation guidance.
🧹 Nitpick comments (1)
README.md (1)
303-315: Intentional--extra-index-urlfor stable cu130, but consider a comment.For cu130, using
--index-urlcan fail becausecuda-bindings==13.0.3is missing from the cu130 wheel index, while--extra-index-url(which also queries PyPI) works around this. Using--extra-index-urlhere is therefore intentional. However, it is visually inconsistent with every other GPU section (all use--index-url), and a future editor might "fix" it back to--index-urland break the install.Consider adding a brief inline comment to preserve intent:
📝 Suggested doc note
-pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130 +# Note: --extra-index-url (not --index-url) is required here; cu130 cuda-bindings +# are not fully mirrored in the PyTorch-only index. +pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 303 - 315, The stable cu130 pip install uses "--extra-index-url" intentionally to fall back to PyPI for the missing package (e.g., the line "pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130"); add a brief inline comment immediately above or on that same line in README.md explaining this intent (mention "cuda-bindings==13.0.3 is missing from the cu130 wheel index, so we use --extra-index-url to also query PyPI") so future editors won't change it to "--index-url".
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Around line 395-400: The "Place your models" table only lists Checkpoints and
VAE and omits other model types referenced elsewhere; update the table under the
"Place your models" heading to include the commonly used directories (e.g.,
LoRAs -> models/lora, embeddings/textual inversion -> models/embeddings,
ControlNet -> models/controlnet, upscalers/upscale models -> models/upscale,
hypernetworks -> models/hypernetworks, etc.) and/or add a clear link to the full
extra_model_paths.yaml.example so readers can see the complete set; ensure the
table entries match the names used in the Features section and the README
references to those directories.
- Around line 253-263: Update the README's ROCm installation section: remove or
replace the two pip install lines that reference the non-existent wheel index
URLs containing "rocm7.2" and "nightly/rocm7.2"; instead mention the currently
published PyTorch ROCm wheel indices (e.g., stable ROCm 6.3/6.4 and nightly ROCm
7.0) or point users to AMD's official ROCm 7.2 manylinux repository
(https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/) for wheels, and add a
short note clarifying that PyTorch does not publish rocm7.2 wheels on
download.pytorch.org so users should use the AMD repo or supported PyTorch ROCm
versions.
---
Duplicate comments:
In `@README.md`:
- Around line 230-239: This README venv activation block (the fenced code block
starting with "python -m venv venv" and containing the Linux/macOS, Windows
(PowerShell), and Windows (CMD) activation lines) is correct and mirrors the
comfy-cli section — no code changes required; leave this block as-is and remove
any duplicate review tags like "[duplicate_comment]" from the PR metadata if
present.
- Around line 199-216: The PR contains a duplicated reviewer note
(duplicate_comment) while the README's virtualenv activation block already
correctly includes both PowerShell (Activate.ps1) and CMD (activate.bat)
instructions; remove the redundant duplicate review comment/marker from the PR
so there’s a single approval and leave the README activation code block (the
lines mentioning Activate.ps1 and activate.bat) as-is to retain Windows
activation guidance.
---
Nitpick comments:
In `@README.md`:
- Around line 303-315: The stable cu130 pip install uses "--extra-index-url"
intentionally to fall back to PyPI for the missing package (e.g., the line "pip
install torch torchvision torchaudio --extra-index-url
https://download.pytorch.org/whl/cu130"); add a brief inline comment immediately
above or on that same line in README.md explaining this intent (mention
"cuda-bindings==13.0.3 is missing from the cu130 wheel index, so we use
--extra-index-url to also query PyPI") so future editors won't change it to
"--index-url".
| Stable ROCm 7.2: | ||
|
|
||
| ```pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm7.2``` | ||
| ```bash | ||
| pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2 | ||
| ``` | ||
|
|
||
| ROCm 7.2 nightly (may have performance improvements): | ||
|
|
||
| ### AMD GPUs (Experimental: Windows and Linux), RDNA 3, 3.5 and 4 only. | ||
| ```bash | ||
| pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm7.2 | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
PyTorch rocm7.2 wheel index https://download.pytorch.org/whl/rocm7.2 2025 2026
💡 Result:
https://download.pytorch.org/whl/rocm7.2does not appear to be a published PyTorch wheel index (at least, it’s not referenced in official PyTorch/AMD install guidance for 2025–2026).- In late 2025, PyTorch’s documented ROCm wheel support focused on ROCm 6.3/6.4 (variant wheels), and explicitly notes that ROCm 7.x variant wheels weren’t available; for ROCm 7.0, it points to a nightly index instead:
https://download.pytorch.org/whl/nightly/rocm7.0. (amd.com) - For ROCm 7.2, AMD’s ROCm documentation directs users to AMD’s wheel hosting (not download.pytorch.org), e.g.
https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/with wheels liketorch-2.9.1+rocm7.2.0...whlandtorchvision-0.24.0+rocm7.2.0...whl. (rocm.docs.amd.com)
Citations:
- 1: https://www.amd.com/en/developer/resources/technical-articles/2025/pytorch-2-9-wheel-variant-support-expands-to-rocm.html?utm_source=openai
- 2: https://rocm.docs.amd.com/projects/radeon-ryzen/en/latest/docs/install/installrad/native_linux/install-pytorch.html?utm_source=openai
🌐 Web query:
PyTorch ROCm versions supported 2025 2026 rocm7.0 rocm7.2
💡 Result:
Linux (official ROCm “PyTorch compatibility” guidance, 2025–2026)
-
ROCm 7.0.x: supported with PyTorch 2.7 and 2.8 (ROCm docs explicitly call out “PyTorch 2.7/2.8 with ROCm 7.0”). [1]
ROCm 7.0.0 itself also states it enables PyTorch 2.7. [2] -
ROCm 7.1 / 7.1.1: supported with PyTorch 2.8 (ROCm 7.1) and PyTorch 2.9 (ROCm 7.1.1). [1]
ROCm 7.1.1 release notes also say it enables PyTorch 2.9. [3] -
ROCm 7.2.0 (released Jan 21, 2026): ROCm’s release notes do not list a new PyTorch version bump, and the ROCm “PyTorch compatibility” page (last updated Dec 10, 2025) only enumerates support up through ROCm 7.1.1 (PyTorch 2.9) and ROCm 7.0 (PyTorch 2.7/2.8). So, as of the latest ROCm docs, there isn’t a published “PyTorch X with ROCm 7.2” pairing in that table yet. [4] [1]
(ROCm 7.2.0 release date for reference.) [5]
Wheels / packaging notes (often what people mean by “supported”)
- PyTorch 2.10 wheel variants list ROCm 7.0 and 7.1 variants (not 7.2). [6]
- AMD’s PyTorch 2.9 “variant wheels” article explicitly says no variant wheels for ROCm 7.0 (they were for ROCm 6.3/6.4), and suggests nightly wheels for ROCm 7.0 via the nightly index URL. [7]
Windows (AMD “PyTorch on Windows” track)
- AMD’s “PyTorch on Windows Edition 7.2” release notes say it’s updated with ROCm 7.2 (released Jan 21, 2026). [8]
- ROCm-on-Windows compatibility matrices (example shown for ROCm 7.1.1) list PyTorch 2.9 + ROCm 7.1.1. [9]
Sources:
[1] [turn7view0] • [2] [turn3search3] • [3] [turn3search4] • [4] [turn5view0] • [5] [turn4search3] • [6] [turn4search5] • [7] [turn4search0] • [8] [turn4search6] • [9] [turn3search2]
🌐 Web query:
PyTorch official documentation ROCm wheel installation index
💡 Result:
PyTorch ROCm pip wheel index (official):
-
Stable ROCm wheels (Linux only): use
--index-url https://download.pytorch.org/whl/rocm<ROCM_VERSION>(example shown for ROCm 6.4). [1] -
Nightly ROCm wheels: use
--index-url https://download.pytorch.org/whl/nightly/rocm<ROCM_VERSION>(example shown for ROCm 7.0). [2]
Examples
# Stable (example: ROCm 6.4)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.4# Nightly (example: ROCm 7.0)
pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm7.0Sources: [1] [2]
Remove or correct rocm7.2 installation instructions — the wheel index does not exist at download.pytorch.org.
The PyTorch wheel indices https://download.pytorch.org/whl/rocm7.2 and https://download.pytorch.org/whl/nightly/rocm7.2 are not published. As of late 2025, PyTorch's documented ROCm wheel support focuses on ROCm 6.3/6.4 (stable) and ROCm 7.0 (nightly); ROCm 7.2 (released January 21, 2026) is not yet paired with a published PyTorch wheel variant in the official index. For ROCm 7.2 support, AMD directs users to AMD's own wheel repository at https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/ instead. Users following the current instructions will encounter installation errors.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 253 - 263, Update the README's ROCm installation
section: remove or replace the two pip install lines that reference the
non-existent wheel index URLs containing "rocm7.2" and "nightly/rocm7.2";
instead mention the currently published PyTorch ROCm wheel indices (e.g., stable
ROCm 6.3/6.4 and nightly ROCm 7.0) or point users to AMD's official ROCm 7.2
manylinux repository (https://repo.radeon.com/rocm/manylinux/rocm-rel-7.2/) for
wheels, and add a short note clarifying that PyTorch does not publish rocm7.2
wheels on download.pytorch.org so users should use the AMD repo or supported
PyTorch ROCm versions.
| ## Place your models | ||
|
|
||
| For AMD 7600 and maybe other RDNA3 cards: ```HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py``` | ||
| | Type | Directory | | ||
| |------|-----------| | ||
| | Checkpoints (`.ckpt` / `.safetensors`) | `models/checkpoints` | | ||
| | VAE | `models/vae` | |
There was a problem hiding this comment.
"Place your models" table is missing several commonly used model directories.
The new table only lists Checkpoints and VAE, but the Features section references LoRAs, embeddings (textual inversion), ControlNet, upscale models, hypernetworks, etc. Users placing those files will have no guidance here.
Consider expanding the table (or linking to the full extra_model_paths.yaml.example file for reference):
📝 Suggested additions
| Checkpoints (`.ckpt` / `.safetensors`) | `models/checkpoints` |
| VAE | `models/vae` |
+| LoRA / LoCon / LoHa | `models/loras` |
+| ControlNet | `models/controlnet` |
+| Upscale models | `models/upscale_models` |
+| Embeddings / Textual Inversion | `models/embeddings` |
+| Hypernetworks | `models/hypernetworks` |
+| VAE approximation (TAESD) | `models/vae_approx` |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## Place your models | |
| For AMD 7600 and maybe other RDNA3 cards: ```HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py``` | |
| | Type | Directory | | |
| |------|-----------| | |
| | Checkpoints (`.ckpt` / `.safetensors`) | `models/checkpoints` | | |
| | VAE | `models/vae` | | |
| ## Place your models | |
| | Type | Directory | | |
| |------|-----------| | |
| | Checkpoints (`.ckpt` / `.safetensors`) | `models/checkpoints` | | |
| | VAE | `models/vae` | | |
| | LoRA / LoCon / LoHa | `models/loras` | | |
| | ControlNet | `models/controlnet` | | |
| | Upscale models | `models/upscale_models` | | |
| | Embeddings / Textual Inversion | `models/embeddings` | | |
| | Hypernetworks | `models/hypernetworks` | | |
| | VAE approximation (TAESD) | `models/vae_approx` | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 395 - 400, The "Place your models" table only lists
Checkpoints and VAE and omits other model types referenced elsewhere; update the
table under the "Place your models" heading to include the commonly used
directories (e.g., LoRAs -> models/lora, embeddings/textual inversion ->
models/embeddings, ControlNet -> models/controlnet, upscalers/upscale models ->
models/upscale, hypernetworks -> models/hypernetworks, etc.) and/or add a clear
link to the full extra_model_paths.yaml.example so readers can see the complete
set; ensure the table entries match the names used in the Features section and
the README references to those directories.
There was a problem hiding this comment.
You must be the good idea fairy. Can you just give me a complete rundown on what I should add/change/delete so I don't have 1.5 million commits for a simple task?
There was a problem hiding this comment.
🧩 Analysis chain
@c0dezer019, absolutely! Let me check the actual model directories ComfyUI uses so I can give you the complete list in one shot.
🏁 Script executed:
#!/bin/bash
# Check the example config file to see what model directories are actually defined
cat extra_model_paths.yaml.example
Length of output: 1885
@c0dezer019, got it! Here's the complete table replacement. One change, done:
Replace lines 395-400 with:
## Place your models
| Type | Directory |
|------|-----------|
| Checkpoints (`.ckpt` / `.safetensors`) | `models/checkpoints` |
| VAE | `models/vae` |
| LoRA / LoCon / LoHa | `models/loras` |
| Embeddings / Textual Inversion | `models/embeddings` |
| ControlNet | `models/controlnet` |
| Upscale models (ESRGAN, SwinIR, etc.) | `models/upscale_models` |
| Hypernetworks | `models/hypernetworks` |
| CLIP / Text encoders | `models/text_encoders` or `models/clip` |
| CLIP Vision | `models/clip_vision` |
| GLIGEN | `models/gligen` |
| VAE approximation (TAESD for previews) | `models/vae_approx` |
| Configs | `models/configs` |
For a complete list of all supported model directories, see the [`extra_model_paths.yaml.example`](extra_model_paths.yaml.example) file.This covers everything mentioned in your Features section and adds the reference link to the config file for advanced users. One commit, done deal! ✨
Test Evidence CheckIf this PR modifies behavior that requires testing, a test explanation is required. PRs lacking applicable test explanations may not be reviewed until added. Please add test explanations to ensure code quality and prevent regressions. If this PR changes user-facing behavior, visual proof (screen recording or screenshot) is required. PRs without applicable visual documentation may not be reviewed until provided. You can add it by:
|
Restructured the layout for a better look and added specific instructions for venv setup.
Move essentials_category from deprecated/incorrect nodes to their replacements: - ImageBatch → BatchImagesNode (ImageBatch is deprecated) - Blur → removed (should use subgraph blueprint) - GetVideoComponents → Video Slice Amp-Thread-ID: https://ampcode.com/threads/T-019c8340-4da2-723b-a09f-83895c5bbda5
… ints, which the glDeleteTextures function does not accept, explicitly cast to int (#12650)
4 participants
This makes the README easier to read. I also fixed installation instructions to include instructions to use a venv to ensure a user unfamiliar or new to Python doesn't nuke their system Python. Case-in-point: Comfy uses deps like numpy that may be used by other non-Comfy packages and Comfy changing the version may break that package, or vice versa. It is also more appropriate to use a venv for installing non-system packages and modules at any rate.