Skip to content

Update settings documentation to match frontend code #1037

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lin-bot23 wants to merge 9 commits into
base: main
Choose a base branch
from
Open

Update settings documentation to match frontend code #1037

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
68bc5b9
Update settings documentation to match frontend code
lin-bot23 May 26, 2026
02cea66
Update zh/ja settings docs to match frontend code
lin-bot23 May 26, 2026
9fc20d7
Fix supported languages list: add missing locale options
lin-bot23 May 26, 2026
6fc4d70
fix: apply audit fixes to settings docs (3d, about, extension, server…
lin-bot23 May 26, 2026
92bb715
fix: update overview.mdx and comfy-desktop.mdx to match frontend
lin-bot23 May 26, 2026
0aa5fbc
fix: escape bare URL in about.mdx to fix mint parse error
lin-bot23 May 30, 2026
69ab72f
Merge remote-tracking branch 'origin/main' into update/settings-docs …
lin-bot23 May 30, 2026
b1a9cd5
sync EN settings docs changes to ZH/JA (overview + about)
lin-bot23 May 30, 2026
c69fcee
fix: use MDX comment syntax instead of HTML comment in extension.mdx
lin-bot23 Jul 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions interface/settings/3d.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,17 +55,26 @@ The light settings in this section are used to set the default lighting settings
Change the background color, which can also be adjusted in the canvas.
![Initial Background Color vs Modified](/images/interface/setting/3d/background_color.jpg)

### Initial Preview Visibility
- **Function**: Controls whether the preview screen is displayed by default when creating new 3D components. This default setting can still be toggled individually for each component after creation
- **Default Value**: true (enabled)

![Preview vs hide preview](/images/interface/setting/3d/hide_preview.jpg)


### Initial Grid Visibility
- **Function**: Controls whether the grid is displayed by default when creating new 3D components. This default setting can still be toggled individually for each component after creation
- **Default Value**: true (enabled)

Hide or show the grid on initialization

![Show grid vs hide grid](/images/interface/setting/3d/hide_grid.jpg)


## 3D Viewer

### Enable 3D Viewer (Beta)
- **Setting ID**: `Comfy.Load3D.3DViewerEnable`
- **Type**: boolean
- **Default Value**: false (disabled)
- **Function**: Controls whether the 3D Viewer (Beta) is enabled. When enabled, a button will appear on 3D component nodes that can be clicked to open a full-size 3D viewer

### PLY Engine
- **Setting ID**: `Comfy.Load3D.PLYEngine`
- **Type**: combo
- **Options**: `threejs`, `fastply`, `sparkjs`
- **Default Value**: `threejs`
- **Function**: Selects the engine used to load PLY files. `threejs` uses the native Three.js PLYLoader (best for mesh PLY files), `fastply` uses a loader optimized for ASCII point cloud PLY files, and `sparkjs` uses Spark.js to load 3D Gaussian Splatting PLY files
47 changes: 41 additions & 6 deletions interface/settings/about.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,20 @@ The About page is an information display panel in the ComfyUI settings system, u

The About page displays the following core version information:

- **ComfyUI Version**: Shows the backend ComfyUI version number, linked to the official GitHub repository
- **ComfyUI Version**: Shows the backend ComfyUI version. The format depends on the distribution:
- **OSS (Open Source)**: Displays `ComfyUI <commit hash>`, linked to the main [GitHub repository](https://github.com/Comfy-Org/ComfyUI)
- **Desktop**: Displays `ComfyUI v<version>`, linked to the same GitHub repository
- **Cloud**: Displays `ComfyUI <commit hash>`, linked to [comfy.org](https://www.comfy.org) with a cloud icon
- **ComfyUI_frontend Version**: Shows the frontend interface version number, linked to the frontend GitHub repository
- **Templates Version**: If `systemStats.system.installed_templates_version` is available, a Templates badge is displayed:
- Label: `Templates v<version>`
- Link: [https://pypi.org/project/comfyui-workflow-templates/](https://pypi.org/project/comfyui-workflow-templates/)
- Icon: `pi pi-book`
- If the installed version differs from the required version, the badge appears with a **danger** severity level (red)
Comment on lines +25 to +29

@coderabbitai coderabbitai Bot Jul 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
fd -e ts -e tsx -e vue -e js |
  xargs rg -n -C3 \
    'installed_templates_version|required_templates_version|severity.*danger'

Repository: Comfy-Org/docs

Length of output: 156

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== Files with about.mdx ==\n'
git ls-files 'interface/settings/about.mdx' 'ja/interface/settings/about.mdx' 'zh/interface/settings/about.mdx' || true

printf '\n== Search for templates version references ==\n'
rg -n -C 3 'installed_templates_version|required_templates_version|Templates v|Templates バージョン|Templates 版本|severity.*danger|danger styling|outdated version' .

printf '\n== Search for likely implementation files by templates term ==\n'
rg -n -C 3 'templates' interface ja zh src app docs . | head -n 300

Repository: Comfy-Org/docs

Length of output: 33758

🌐 Web query:

ComfyUI frontend installed_templates_version required_templates_version Templates danger severity

💡 Result:

In ComfyUI, installed_templates_version and required_templates_version are system parameters used to manage the compatibility between the core ComfyUI application and the installed workflow templates package [1][2][3]. These fields are exposed via the /system_stats endpoint [2][3]. Their primary purpose is to allow the frontend to detect version mismatches [4]. When the installed version of the workflow templates does not meet the requirements defined in ComfyUI's requirements.txt, the system may trigger warnings or toast notifications to alert the user [2][4]. Regarding "danger" or "severity" levels: ComfyUI does not typically categorize these version mismatches with explicit "danger" or "severity" metadata levels (such as high, medium, or low) in its core code [1][3]. Instead, the system handles these as compatibility checks [4]: 1. Version Mismatch: If a mismatch is detected, the system generates logs and warnings [4]. Users often experience this as "missing node" errors, 404 errors when loading templates, or simply the disappearance of certain template options from the UI [5][6][7][8]. 2. Resolution: These issues are generally resolved by updating the comfyui-workflow-templates package in the user's Python environment (e.g., using pip install --upgrade comfyui-workflow-templates) or by ensuring both ComfyUI and the manager are up to date [8][9]. While there is no formal severity scale, a version mismatch is functionally critical for specific features; if the templates are outdated, the associated workflows or nodes will often fail to execute or load, rendering those specific features non-functional [5][6][8].

Citations:

Keep the Templates danger wording consistent across locales. The badge text uses a version mismatch, but the system-info summary says only “outdated.” Keep the English, Japanese, and Chinese pages in lockstep so the docs don’t turn into a mismatch mishmash.

📍 Affects 3 files
  • interface/settings/about.mdx#L25-L29 (this comment)
  • interface/settings/about.mdx#L56-L56
  • ja/interface/settings/about.mdx#L27-L31
  • ja/interface/settings/about.mdx#L58-L58
  • zh/interface/settings/about.mdx#L25-L29
  • zh/interface/settings/about.mdx#L56-L56
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@interface/settings/about.mdx` around lines 25 - 29, Align the Templates badge
and system-info summary wording so all locales consistently describe a version
mismatch rather than using “outdated” inconsistently. Update
interface/settings/about.mdx lines 25-29 and 56, ja/interface/settings/about.mdx
lines 27-31 and 58, and zh/interface/settings/about.mdx lines 25-29 and 56,
preserving each locale’s language while keeping the English, Japanese, and
Chinese descriptions semantically in lockstep.

- **Discord Community**: Provides a link to the ComfyOrg Discord server
- **Official Website**: Links to the ComfyOrg official website
- **ComfyOrg**: Links to the ComfyOrg official website

The badges are displayed in the following order: ComfyUI → Frontend → Templates (if installed) → Discord → ComfyOrg.

<Tip>
Since the version information here mainly corresponds to stable version information, if you are using the nightly version, the corresponding commit hash will not be displayed here. If you are using the nightly version, you can use the `git log` command in the corresponding ComfyUI main directory to view the corresponding commit hash and other information.
Expand All @@ -33,10 +43,35 @@ If custom nodes are installed, the About page will also display additional badge

### System Info

The bottom of the page displays detailed system statistics, including:
- Hardware configuration information
- Software environment information
- System performance data
The bottom of the page displays detailed system statistics, which vary depending on the distribution:

**OSS / General Version:**
- **OS**: Operating system identifier
- **Python Version**: Installed Python version
- **Embedded Python**: Embedded Python details (if applicable)
- **Pytorch Version**: PyTorch framework version
- **Arguments (argv)**: Command-line arguments used to launch ComfyUI
- **RAM Total**: Total available system RAM
- **RAM Free**: Currently free system RAM
- **Templates Version**: Shown with danger styling if the installed version is outdated

**Cloud Version:**
- **Cloud Version**: Cloud platform version
- **ComfyUI Version**: Backend ComfyUI version
- **Frontend Version**: Frontend interface version
- **Templates Version**: Workflow templates version

**Devices** (displayed when compatible hardware is detected):
- Device name and type (e.g. GPU model)
- **VRAM Total / VRAM Free**: Graphics memory statistics
- **Torch VRAM Total / Torch VRAM Free**: PyTorch-managed VRAM statistics
- Multiple devices are presented in a **TabView**, one tab per device

A **Copy System Info** button is provided at the bottom, which copies all system information in a formatted text block to the clipboard for easy sharing when reporting issues.

### Version Update Notifications

The `ShowVersionUpdates` setting (found under Comfy → Notification Preferences) controls whether version update notifications are shown on the About page and elsewhere in the interface.

## Extension Developer Guide

Expand Down
83 changes: 65 additions & 18 deletions interface/settings/comfy-desktop.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Comfy Desktop General Settings"
description: "Detailed description of ComfyUI Desktop general setting options"
description: "Detailed description of ComfyUI Desktop specific setting options"
icon: "desktop"
sidebarTitle: "Comfy Desktop"
---
Expand All @@ -9,31 +9,78 @@ import SettingsMenuContext from "/snippets/interface/settings-menu-context.mdx"

<SettingsMenuContext />

The Comfy Desktop settings section contains settings that are specific to the ComfyUI Desktop application (Electron-based). These settings are registered by the `Comfy.ElectronAdapter` extension and only appear when running ComfyUI Desktop. Changes to several of these settings require restarting the application to take effect.

## General

### Window Style
**Function**: Controls the title bar style of the application window
- **Setting ID**: `Comfy-Desktop.WindowStyle`
- **Type**: combo
- **Options**: `default`, `custom`
- **Default Value**: `default`
- **Experimental**: Yes
- **Function**: Controls the title bar style of the application window. The `custom` option replaces the system title bar with ComfyUI's built-in Top menu.

### Automatically check for updates
**Function**: Automatically checks for ComfyUI Desktop updates and will remind you to update when updates are available

- **Setting ID**: `Comfy-Desktop.AutoUpdate`
- **Type**: boolean
- **Default Value**: true (enabled)
- **Function**: Automatically checks for ComfyUI Desktop updates and will notify you when updates are available. Changes require a restart to take effect.

### Send anonymous usage metrics
**Function**: Sends anonymous usage statistics to help improve the software. Changes to this setting require a restart to take effect
- **Setting ID**: `Comfy-Desktop.SendStatistics`
- **Type**: boolean
- **Default Value**: true (enabled)
- **Function**: Sends anonymous usage statistics to help improve the software. Changes require a restart to take effect.

## UV (Mirror Settings)

## UV
The UV section provides mirror configuration for users in China and other regions where default download sources may be slow or inaccessible. Use this section to configure alternative download mirrors for Python distributions, pip packages, and PyTorch packages.

All UV settings are of type `url` and support:
- HTTP/HTTPS URLs for remote mirrors
- `file://` URLs for local directory distribution packages
- Automatic reachability validation

This section is mainly for users in China, because many of the original mirrors used by Desktop are outside of China, so access may not be friendly for domestic users. You can set your own mirror sources here to improve access speed and ensure that corresponding packages can be accessed and downloaded normally.

### Python Install Mirror
**Function**:
- Managed Python installation packages are downloaded from the Astral python-build-standalone project
- Can set mirror URL to use different Python installation sources
- The provided URL will replace the default GitHub download address
- Supports using file:// protocol to read distribution packages from local directories
**Validation**: Automatically checks mirror reachability

- **Setting ID**: `Comfy-Desktop.UV.PythonInstallMirror`
- **Type**: url
- **Default Value**: empty string (uses default GitHub source)
- **Tooltip**: Managed Python installations are downloaded from the Astral python-build-standalone project. This variable can be set to a mirror URL to use a different source for Python installations. The provided URL will replace `https://github.com/astral-sh/python-build-standalone/releases/download` in distribution URLs. Distributions can be read from a local directory by using the `file://` URL scheme.
- **Validation**: Automatically checks mirror reachability with a ping suffix

### Pypi Install Mirror
**Function**: Default pip package installation mirror source

- **Setting ID**: `Comfy-Desktop.UV.PypiInstallMirror`
- **Type**: url
- **Default Value**: empty string (uses default pip source)
- **Function**: Default pip package installation mirror source
- **Tooltip**: Default pip install mirror
- **Validation**: Automatically checks mirror reachability

### Torch Install Mirror
**Function**: PyTorch-specific pip installation mirror source
- **Setting ID**: `Comfy-Desktop.UV.TorchInstallMirror`
- **Type**: url
- **Default Value**: empty string (uses default PyTorch source)
- **Function**: PyTorch-specific pip installation mirror source
- **Tooltip**: Pip install mirror for pytorch
- **Validation**: Automatically checks mirror reachability

## Available Commands

In addition to settings, Desktop users have access to the following commands (accessible from the Help menu):

### Open Folders
- **Open Logs Folder** — Opens the ComfyUI Desktop logs folder
- **Open Models Folder** — Opens the models directory
- **Open Outputs Folder** — Opens the outputs directory
- **Open Inputs Folder** — Opens the inputs directory
- **Open Custom Nodes Folder** — Opens the custom nodes directory
- **Open extra_model_paths.yaml** — Opens the model configuration file

### Application Commands
- **Check for Updates** — Manually check for ComfyUI Desktop updates
- **Reinstall** — Reinstall ComfyUI Desktop
- **Restart** — Restart the application
- **Quit** — Quit the application
- **Open DevTools** — Open Chrome Developer Tools
- **Desktop User Guide** — Open the Desktop user guide in a browser
Loading