## 1. Project Overview & Quickstart (Comfy-Org/ComfyUI) ## File: README.md ComfyUI is the AI creation engine for visual professionals who demand control over every model, every parameter, and every output. Its powerful and modular node graph interface empowers creatives to generate images, videos, 3D models, audio, and more... - ComfyUI natively supports the latest open-source state of the art models. - [Partner nodes](https://docs.comfy.org/tutorials/partner-nodes/overview#partner-nodes) provide access to the best closed source models such as Nano Banana, Seedance, Hunyuan3D, etc. - It is available on Windows, Linux, and macOS, locally with our [desktop application](https://www.comfy.org/download), our [portable install](#installing) or on our [cloud](https://www.comfy.org/cloud). - The most sophisticated workflows can be exposed through a simple UI thanks to App Mode. - It integrates seamlessly into production pipelines with our API endpoints. ## Get Started ### Local #### [Desktop Application](https://www.comfy.org/download) - The easiest way to get started. - Available on Windows & macOS. #### [Windows Portable Package](#installing) - Get the latest commits and completely portable. - Available on Windows. #### [Manual Install](#manual-install-windows-linux) Supports all operating systems and GPU types (NVIDIA, AMD, Intel, Apple Silicon, Ascend). ### Cloud #### [Comfy Cloud](https://www.comfy.org/cloud) - Our official paid cloud version for those who can't afford local hardware. ## Examples See what ComfyUI can do with the [newer template workflows](https://comfy.org/workflows) or old [example workflows](https://comfyanonymous.github.io/ComfyUI_examples/). ## Features - A visual node graph for building and reusing image, video, audio, 3D, and text workflows without code. - Reusable subgraphs, workflow templates, App Mode, and a local API for integrating workflows into applications. - Efficient local execution with asynchronous queueing, partial graph re-execution, smart VRAM and RAM management, model offloading, and support for quantized models. - Broad native model support. This is a representative list; browse the [workflow library](https://comfy.org/workflows/) for maintained, ready-to-run templates. - [Image generation](https://comfy.org/workflows/tag/text-to-image/): Stable Diffusion 1.5, SDXL, SD3.5, Flux.1, Flux.2, Qwen Image, Z-Image, Hunyuan Image 2.1, HiDream, Lumina Image 2.0, Chroma, Anima, LongCat Image, Ideogram 4, Krea 2, MageFlow, Microsoft Lens, PixelDiT, Kandinsky 5, and Ernie Image. - [Image editing](https://comfy.org/workflows/tag/image-edit/): Flux Kontext, Flux.2 Klein, Qwen Image Edit, HiDream E1.1 and O1, OmniGen2, Boogu, JoyImage Edit, MageFlow Edit, and LongCat Image Edit. - [Video generation](https://comfy.org/workflows/tag/video-generation/): Wan 2.1 and 2.2, LTX-Video 2 and 2.3, HunyuanVideo 1.5, Kandinsky 5 Video, CogVideoX, Cosmos Predict2, Bernini-R, SCAIL 2, and Mochi. - [Audio and video generation](https://comfy.org/workflows/): MiniMax H3 and LTX-AV. - [Audio generation](https://comfy.org/workflows/tag/text-to-audio/): ACE-Step 1.5, Stable Audio 3 and MiniMax Music 3 - [3D and vision](https://comfy.org/workflows/): Hunyuan3D 2.1, TripoSplat, SeedVR2, SUPIR, Depth Anything 3, MoGe, SAM 3 and 3.1, RT-DETRv4, and BiRefNet. - [Text generation](https://comfy.org/workflows/tag/text-generation/): Gemma 3 and 4, Qwen3, Qwen3.5, and Qwen3-VL, including multimodal inputs. - Load complete checkpoints or separate diffusion models, VAEs, text encoders, LoRAs, ControlNets, adapters, and upscalers from supported model formats. - Built-in tools for inpainting, outpainting, reference conditioning, masks and compositing, model merging, upscaling, frame interpolation, segmentation, depth estimation, and media processing. - Save and load workflows as JSON, or recover complete workflows and seeds from supported generated media. - Runs fully offline: core does not download anything unless you request it. Use `--disable-api-nodes` to disable the optional paid [Comfy API nodes](https://docs.comfy.org/tutorials/api-nodes/overview) and force all built-in functionality to stay offline. - Extend ComfyUI with custom nodes - Configure additional model locations with [`extra_model_paths.yaml`](extra_model_paths.yaml.example). ## Release Process ComfyUI follows a weekly release cycle targeting Monday but this regularly changes because of model releases or large changes to the codebase. There are three interconnected repositories: 1. **[ComfyUI Core](https://github.com/comfyanonymous/ComfyUI)** - Releases a new major stable version (e.g., v0.7.0) roughly every 2 weeks. - Starting from v0.4.0 patch versions will be used for fixes backported onto the current stable release. - Minor versions will be used for releases off the master branch. - Patch versions may still be used for releases on the master branch in cases where a backport would not make sense. - Commits outside of the stable release tags may be very unstable and break many custom nodes. - Serves as the foundation for the desktop release 2. **[Comfy Desktop](https://github.com/Comfy-Org/Comfy-Desktop)** - Builds a new release using the latest stable core version 3. **[ComfyUI Frontend](https://github.com/Comfy-Org/ComfyUI_frontend)** - Every 2+ weeks frontend updates are merged into the core repository - Features are frozen for the upcoming core release - Development continues for the next release cycle ## Shortcuts | Keybind | Explanation | |------------------------------------|--------------------------------------------------------------------------------------------------------------------| | `Ctrl` + `Enter` | Queue up current graph for generation | | `Ctrl` + `Shift` + `Enter` | Queue up current graph as first for generation | | `Ctrl` + `Alt` + `Enter` | Cancel current generation | | `Ctrl` + `Z`/`Ctrl` + `Y` | Undo/Redo | | `Ctrl` + `S` | Save workflow | | `Ctrl` + `O` | Load workflow | | `Ctrl` + `A` | Select all nodes | | `Alt `+ `C` | Collapse/uncollapse selected nodes | | `Ctrl` + `M` | Mute/unmute selected nodes | | `Ctrl` + `B` | Bypass selected nodes (acts like the node was removed from the graph and the wires reconnected through) | | `Delete`/`Backspace` | Delete selected nodes | | `Ctrl` + `Backspace` | Delete the current graph | | `Space` | Move the canvas around when held and moving the cursor | | `Ctrl`/`Shift` + `Click` | Add clicked node to selection | | `Ctrl` + `C`/`Ctrl` + `V` | Copy and paste selected nodes (without maintaining connections to outputs of unselected nodes) | | `Ctrl` + `C`/`Ctrl` + `Shift` + `V` | Copy and paste selected nodes (maintaining connections from outputs of unselected nodes to inputs of pasted nodes) | | `Shift` + `Drag` | Move multiple selected nodes at the same time | | `Ctrl` + `D` | Load default graph | | `Alt` + `+` | Canvas Zoom in | | `Alt` + `-` | Canvas Zoom out | | `Ctrl` + `Shift` + LMB + Vertical drag | Canvas Zoom in/out | | `P` | Pin/Unpin selected nodes | | `Ctrl` + `G` | Group selected nodes | | `Q` | Toggle visibility of the queue | | `H` | Toggle visibility of history | | `R` | Refresh graph | | `F` | Show/Hide menu | | `.` | Fit view to selection (Whole graph when nothing is selected) | | Double-Click LMB | Open node quick search palette | | `Shift` + Drag | Move multiple wires at once | | `Ctrl` + `Alt` + LMB | Disconnect all wires from clicked slot | `Ctrl` can also be replaced with `Cmd` instead for macOS users # Installing ## Windows and Mac We highly recommend using the [desktop app](https://comfy.org/download): ### [Link to Download](https://comfy.org/download) The desktop app is the easiest and best way to use ComfyUI for new users. ## Windows Portable There is a portable standalone build for Windows that should work for running on Nvidia GPUs or for running on your CPU only. It is not recommended for regular users. Regular users should use the desktop app above. [Direct link to download (nvidia)](https://github.com/comfyanonymous/ComfyUI/releases/latest/download/ComfyUI_windows_portable_nvidia.7z) Simply download, extract with [7-Zip](https://7-zip.org) or with the windows explorer on recent windows versions and run. For smaller models you normally only need to put the checkpoints (the huge ckpt/safetensors files) in: ComfyUI\models\checkpoints but many of the larger models have multiple files. Make sure to follow the instructions to know which subfolder to put them in ComfyUI\models\ If you have trouble extracting it, right click the file -> properties -> unblock The portable above currently comes with python 3.13 and pytorch cuda 13.0. Update your Nvidia drivers if it doesn't start. #### All Official Portable Downloads: [Portable for AMD GPUs](https://github.com/comfyanonymous/ComfyUI/releases/latest/download/ComfyUI_windows_portable_amd.7z) [Portable for Intel GPUs](https://github.com/comfyanonymous/ComfyUI/releases/latest/download/ComfyUI_windows_portable_intel.7z) [Portable for Nvidia GPUs](https://github.com/comfyanonymous/ComfyUI/releases/latest/download/ComfyUI_windows_portable_nvidia.7z) (supports 20 series and above). [Portable for Nvidia GPUs with pytorch cuda 12.6 and python 3.12](https://github.com/comfyanonymous/ComfyUI/releases/latest/download/ComfyUI_windows_portable_nvidia_cu126.7z) (Supports Nvidia 10 series and older GPUs, DO NOT USE THIS ON NEWER 20 SERIES AND ABOVE GPUS). #### How do I share models between another UI and ComfyUI? See the [Config file](extra_model_paths.yaml.example) to set the search paths for models. In the standalone windows build you can find this file in the ComfyUI directory. Rename this file to extra_model_paths.yaml and edit it with your favorite text editor. ## [comfy-cli](https://docs.comfy.org/comfy-cli/getting-started) You can install and start ComfyUI using comfy-cli: ```bash pip install comfy-cli comfy install ``` ## Manual Install (Windows, Linux) Python 3.14 works but some custom nodes may have issues. The free threaded variant works but some dependencies will enable the GIL so it's not fully supported. Python 3.13 is very well supported. If you have trouble with some custom node dependencies on 3.13 you can try 3.12 torch 2.7 is minimally supported but using a newer version is extremely recommended. Using a cu130 or above version of pytorch is required on Nvidia 20 series and above. Some features and optimizations might only work on newer versions. We generally recommend using the latest major version of pytorch with the latest cuda version unless it is less than 2 weeks old. If your pytorch is more than 6 months old, please update it. ### Instructions: Git clone this repo. Put your SD checkpoints (the huge ckpt/safetensors files) in: models/checkpoints Put your VAE in: models/vae ### AMD GPUs (Linux) AMD users can install rocm and pytorch with pip if you don't have it already installed, this is the command to install the stable version: ```pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm7.2``` This is the command to install the nightly with ROCm 7.2 which might have some performance improvements: ```pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/rocm7.2``` ### AMD GPUs (Experimental: Windows and Linux), RDNA 3, 3.5 and 4 only. These have less hardware support than the builds above but they work on windows. You also need to install the pytorch version specific to your hardware. RDNA 3 (RX 7000 series): ```pip install --pre torch torchvision torchaudio --index-url https://rocm.nightlies.amd.com/v2/gfx110X-all/``` RDNA 3.5 (Strix halo/Ryzen AI Max+ 365): ```pip install --pre torch torchvision torchaudio --index-url https://rocm.nightlies.amd.com/v2/gfx1151/``` RDNA 4 (RX 9000 series): ```pip install --pre torch torchvision torchaudio --index-url https://rocm.nightlies.amd.com/v2/gfx120X-all/``` ### Intel GPUs (Windows and Linux) Intel Arc GPU users can install native PyTorch with torch.xpu support using pip. More information can be found [here](https://pytorch.org/docs/main/notes/get_start_xpu.html) 1. To install PyTorch xpu, use the following command: ```pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/xpu``` This is the command to install the Pytorch xpu nightly which might have some performance improvements: ```pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/xpu``` ### NVIDIA Nvidia users should install stable pytorch using this command: ```pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130``` This is the command to install pytorch nightly instead which might have performance improvements. ```pip install --pre torch torchvision torchaudio --index-url https://download.pytorch.org/whl/nightly/cu132``` #### Troubleshooting If you get the "Torch not compiled with CUDA enabled" error, uninstall torch with: ```pip uninstall torch``` And install it again with the command above. ### Dependencies Install the dependencies by opening your terminal inside the ComfyUI folder and: ```pip install -r requirements.txt``` After this you should have everything installed and can proceed to running ComfyUI. ### Others: #### Apple Mac silicon You can install ComfyUI in Apple Mac silicon (M1, M2, M3 or M4) with any recent macOS version. 1. Install pytorch nightly. For instructions, read the [Accelerated PyTorch training on Mac](https://developer.apple.com/metal/pytorch/) Apple Developer guide (make sure to install the latest pytorch nightly). 1. Follow the [ComfyUI manual installation](#manual-install-windows-linux) instructions for Windows and Linux. 1. Install the ComfyUI [dependencies](#dependencies). If you have another Stable Diffusion UI [you might be able to reuse the dependencies](#i-already-have-another-ui-for-stable-diffusion-installed-do-i-really-have-to-install-all-of-these-dependencies). 1. Launch ComfyUI by running `python main.py` > **Note**: Remember to add your models, VAE, LoRAs etc. to the corresponding Comfy folders, as discussed in [ComfyUI manual installation](#manual-install-windows-linux). #### Ascend NPUs For models compatible with Ascend Extension for PyTorch (torch_npu). To get started, ensure your environment meets the prerequisites outlined on the [installation](https://ascend.github.io/docs/sources/ascend/quick_install.html) page. Here's a step-by-step guide tailored to your platform and installation method: 1. Begin by installing the recommended or newer kernel version for Linux as specified in the Installation page of torch-npu, if necessary. 2. Proceed with the installation of Ascend Basekit, which includes the driver, firmware, and CANN, following the instructions provided for your specific platform. 3. Next, install the necessary packages for torch-npu by adhering to the platform-specific instructions on the [Installation](https://ascend.github.io/docs/sources/pytorch/install.html#pytorch) page. 4. Finally, adhere to the [ComfyUI manual installation](#manual-install-windows-linux) guide for Linux. Once all components are installed, you can run ComfyUI as described earlier. #### Cambricon MLUs For models compatible with Cambricon Extension for PyTorch (torch_mlu). Here's a step-by-step guide tailored to your platform and installation method: 1. Install the Cambricon CNToolkit by adhering to the platform-specific instructions on the [Installation](https://www.cambricon.com/docs/sdk_1.15.0/cntoolkit_3.7.2/cntoolkit_install_3.7.2/index.html) 2. Next, install the PyTorch(torch_mlu) following the instructions on the [Installation](https://www.cambricon.com/docs/sdk_1.15.0/cambricon_pytorch_1.17.0/user_guide_1.9/index.html) 3. Launch ComfyUI by running `python main.py` #### Iluvatar Corex For models compatible with Iluvatar Extension for PyTorch. Here's a step-by-step guide tailored to your platform and installation method: 1. Install the Iluvatar Corex Toolkit by adhering to the platform-specific instructions on the [Installation](https://support.iluvatar.com/#/DocumentCentre?id=1&nameCenter=2&productId=520117912052801536) 2. Launch ComfyUI by running `python main.py` ## [ComfyUI-Manager](https://github.com/Comfy-Org/ComfyUI-Manager/tree/manager-v4) **ComfyUI-Manager** is an extension that allows you to easily install, update, and manage custom nodes for ComfyUI. ### Setup 1. Install the manager dependencies: ```bash pip install -r manager_requirements.txt ``` 2. Enable the manager with the `--enable-manager` flag when running ComfyUI: ```bash python main.py --enable-manager ``` ### Command Line Options | Flag | Description | |------|-------------| | `--enable-manager` | Enable ComfyUI-Manager | | `--enable-manager-legacy-ui` | Use the legacy manager UI instead of the new UI (implies `--enable-manager`) | | `--disable-manager-ui` | Disable the manager UI and endpoints while keeping background features like security checks and scheduled installation completion (requires `--enable-manager`) | # Running ```python main.py``` ### For AMD cards not officially supported by ROCm Try running it with this command if you have issues: For 6700, 6600 and maybe other RDNA2 or older: ```HSA_OVERRIDE_GFX_VERSION=10.3.0 python main.py``` For AMD 7600 and maybe other RDNA3 cards: ```HSA_OVERRIDE_GFX_VERSION=11.0.0 python main.py``` ### AMD ROCm Tips You can try setting this env variable `PYTORCH_TUNABLEOP_ENABLED=1` which might speed things up at the cost of a very slow initial run. # Notes Only parts of the graph that have an output with all the correct inputs will be executed. Only parts of the graph that change from each execution to the next will be executed, if you submit the same graph twice only the first will be executed. If you change the last part of the graph only the part you changed and the part that depends on it will be executed. Dragging a generated png on the webpage or loading one will give you the full workflow including seeds that were used to create it. You can use () to change emphasis of a word or phrase like: (good code:1.2) or (bad code:0.8). The default emphasis for () is 1.1. To use () characters in your actual prompt escape them like \\( or \\). You can use {day|night}, for wildcard/dynamic prompts. With this syntax "{wild|card|test}" will be randomly replaced by either "wild", "card" or "test" by the frontend every time you queue the prompt. To use {} characters in your actual prompt escape them like: \\{ or \\}. Dynamic prompts also support C-style comments, like `// comment` or `/* comment */`. To use a textual inversion concepts/embeddings in a text prompt put them in the models/embeddings directory and use them in the CLIPTextEncode node like this (you can omit the .pt extension): ```embedding:embedding_filename.pt``` ## How to show high-quality previews? Use ```--preview-method auto``` to enable previews. The default installation includes a fast latent preview method that's low-resolution. To enable higher-quality previews with [TAESD](https://github.com/madebyollin/taesd), download the [taesd_decoder.pth, taesdxl_decoder.pth, taesd3_decoder.pth and taef1_decoder.pth](https://github.com/madebyollin/taesd/) and place them in the `models/vae_approx` folder. Once they're installed, restart ComfyUI and launch it with `--preview-method taesd` to enable high-quality previews. ## How to use TLS/SSL? Generate a self-signed certificate (not appropriate for shared/production use) and key by running the command: `openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 3650 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"` Use `--tls-keyfile key.pem --tls-certfile cert.pem` to enable TLS/SSL, the app will now be accessible with `https://...` instead of `http://...`. > Note: Windows users can use [alexisrolland/docker-openssl](https://github.com/alexisrolland/docker-openssl) or one of the [3rd party binary distributions](https://wiki.openssl.org/index.php/Binaries) to run the command example above. If you use a container, note that the volume mount `-v` can be a relative path so `... -v ".\:/openssl-certs" ...` would create the key & cert files in the current directory of your command prompt or powershell terminal. ## Support and dev channel [Discord](https://comfy.org/discord): Try the #help or #feedback channels. [Matrix space: #comfyui_space:matrix.org](https://app.element.io/#/room/%23comfyui_space%3Amatrix.org) (it's like discord but open source). See also: [https://www.comfy.org/](https://www.comfy.org/) > _psst — we're hiring!_ Help build ComfyUI: [comfy.org/careers](https://www.comfy.org/careers) ## Frontend Development As of August 15, 2024, we have transitioned to a new frontend, which is now hosted in a separate repository: [ComfyUI Frontend](https://github.com/Comfy-Org/ComfyUI_frontend). The compiled JS files (from TS/Vue) are published to [pypi](https://pypi.org/project/comfyui-frontend-package) and installed as a dependency in ComfyUI. ### Reporting Issues and Requesting Features For any bugs, issues, or feature requests related to the frontend, please use the [ComfyUI Frontend repository](https://github.com/Comfy-Org/ComfyUI_frontend). This will help us manage and address frontend-specific concerns more efficiently. ### Using the Latest Frontend The new frontend is now the default for ComfyUI. However, please note: 1. The frontend in the main ComfyUI repository is updated fortnightly. 2. Daily releases are available in the separate frontend repository. To use the most up-to-date frontend version: 1. For the latest daily release, launch ComfyUI with this command line argument: ``` --front-end-version Comfy-Org/ComfyUI_frontend@latest ``` 2. For a specific version, replace `latest` with the desired version number: ``` --front-end-version Comfy-Org/ComfyUI_frontend@1.2.2 ``` This approach allows you to easily switch between the stable fortnightly release and the cutting-edge daily updates, or even specific versions for testing purposes. # QA ### Which GPU should I buy for this? [See this page for some recommendations](https://github.com/comfyanonymous/ComfyUI/wiki/Which-GPU-should-I-buy-for-ComfyUI) --- ## File: alembic_db/README.md ## Generate new revision 1. Update models in `/app/database/models.py` 2. Run `alembic revision --autogenerate -m "{your message}"` --- ## File: api_server/routes/internal/README.md # ComfyUI Internal Routes All routes under the `/internal` path are designated for **internal use by ComfyUI only**. These routes are not intended for use by external applications may change at any time without notice. --- ## File: comfy/comfy_types/README.md # Comfy Typing ## Type hinting for ComfyUI Node development This module provides type hinting and concrete convenience types for node developers. If cloned to the custom_nodes directory of ComfyUI, types can be imported using: ```python from comfy.comfy_types import IO, ComfyNodeABC, CheckLazyMixin class ExampleNode(ComfyNodeABC): @classmethod def INPUT_TYPES(s) -> InputTypeDict: return {"required": {}} ``` Full example is in [examples/example_nodes.py](examples/example_nodes.py). # Types A few primary types are documented below. More complete information is available via the docstrings on each type. ## `IO` A string enum of built-in and a few custom data types. Includes the following special types and their requisite plumbing: - `ANY`: `"*"` - `NUMBER`: `"FLOAT,INT"` - `PRIMITIVE`: `"STRING,FLOAT,INT,BOOLEAN"` ## `ComfyNodeABC` An abstract base class for nodes, offering type-hinting / autocomplete, and somewhat-alright docstrings. ### Type hinting for `INPUT_TYPES` ### `INPUT_TYPES` return dict ### Options for individual inputs --- ## File: tests-unit/README.md # Pytest Unit Tests ## Install test dependencies `pip install -r tests-unit/requirements.txt` ## Run tests `pytest tests-unit/` ## 2. Official Technical Reference & Guides (Comfy-Org/docs) # ComfyUI Documentation | [English](README.md) | [中文](readme/zh-CN.md) | [日本語](readme/ja-JP.md) | [한국어](readme/ko-KR.md) | ## Development To preview documentation changes locally, first install dependencies and then start the development server: ``` npm i npm run dev ``` To sync translations after editing English docs, see [Automated translation](#automated-translation) below (`npm run translate`). ### Create a PR Create a PR. Once it is accepted Vercel will deploy the change to https://docs.comfy.org/ ### Generating API Reference Docs Can either use an OpenAPI file or URL containing the file: ```bash cd registry/api-reference # Keep API files separated by products. npx @mintlify/scraping@latest openapi-file ``` This will only generate the MDX files for each endpoint. You need to add a link to these files in `docs.json`, and the up-to-date API spec will be shown on that doc page. ## Special Note on Renaming Files - Renaming files can cause some external links to become inaccessible, as they are already used in numerous articles and templates. - Since we can manage the sidebar navigation can be reorganized via the docs.json file, we generally do not change the original document's file location unless absolutely necessary. - If you renamed any files and caused the file path to be changed, please update the `redirects` list in the `docs.json` A GitHub Action will check for redirects and fail the PR if they are missing. Redirects should follow this format: > ```json > "redirects": [ > { > "source": "/path/to/old-file", > "destination": "/path/to/new-file" > } > ] > ``` > Don't forget to include the corresponding translation files under `zh/`, `ja/`, `ko/`, etc.! You can also refer to the [Mintlify doc](https://www.mintlify.com/docs/create/redirects) to learn how to add and match a wildcard path. ## About built-in node document ComfyUI now has a built-in node help menu for both built-in nodes and custom nodes. All built-in node documentation will now be maintained in [this repo](https://github.com/Comfy-Org/embedded-docs). ### Synchronization frequency We will regularly sync updated documentation from the corresponding repository to docs.comfy.org weekly to ensure content synchronization and updates. If you would like to contribute to the documentation, please submit PRs and updates to [this repo](https://github.com/Comfy-Org/embedded-docs). ### Node Documentation File Organization For node documentation, we will use a single-level directory structure under the `built-in-node` folder for the following reasons: - ComfyUI may adjust node categories and directories during updates, using multi-level directory hierarchies means frequent adjustments to node documentation - These frequent adjustments mean we need to frequently add redirects and checks - Mintlify supports setting document hierarchy in the `docs.json` file, so we can make unified changes in that file > Due to historical updates, some existing documents use different folder hierarchies. We will no longer adjust these files, but new files will use a single-level directory ## Contributing Please just create a PR and we will review it within a few days. Or talk to us on our [discord](https://discord.com/invite/comfyorg) The documentation is built with Mintlify, please refer to [Mintlify documentation](https://mintlify.com/docs) to learn how to use it. ### i18n Contributions English MDX at the repo root is the **source of truth**. Translations mirror the same relative paths under language directories (for example `zh/get_started/introduction.mdx`, `ja/get_started/introduction.mdx`, `ko/get_started/introduction.mdx`). Reusable fragments live in `snippets/` with per-language copies under `snippets/zh/`, `snippets/ja/`, `snippets/ko/`, and so on. Contributing guides in other languages: [readme/](readme/) (中文, 日本語, 한국어). **Translation policy** Supported locales are maintained through **automated translation** from English. When English docs change, translations are updated in batch via `npm run translate` — contributors do not need to hand-translate every page. **Request a new language** Want docs in another language? [Open an issue](https://github.com/Comfy-Org/docs/issues/new) with the locale you need (for example French, German, or Brazilian Portuguese). A maintainer will add the language to `translation-config.json` and `docs.json`, then run a **full batch translation** of all content. You only need to submit the request; no translated MDX PR is required to get started. Specifications for editing MDX can be found in the Writing Content section of the [Mintlify](https://mintlify.com/docs/page) document. > **Note**: `built-in-nodes/` is maintained in [embedded-docs](https://github.com/Comfy-Org/embedded-docs) and is **skipped** by the translation script. Do not run bulk translation against that folder. #### Automated translation This repo includes a hash-based translation script. It compares each English file against `translationSourceHash` stored in the translated file; when the English source changes, the file is fully re-translated. **Prerequisites** 1. Install [Bun](https://bun.sh) 2. Copy the env template and add your API key: ```bash cp .env.local.example .env.local # Set TRANSLATE_API_KEY (OpenAI-compatible: DashScope Qwen-MT, OpenRouter, DeepSeek, etc.) ``` **npm scripts** | Command | Description | |---------|-------------| | `npm run translate` | Translate all languages listed in `translation-config.json` | | `npm run translate:dry-run` | List pending files without calling the API | | `npm run translate:force` | Re-translate everything, ignoring stored hashes | | `npm run translate:snippets` | Translate `snippets/` only | | `npm run translate:snippets:dry-run` | Preview pending snippet translations | | `npm run translate:check-truncation` | Scan for likely truncated translations | | `npm run translate:repair-truncated` | Re-translate files listed in the truncation log | | `npm run glossary:sync` | Rebuild the terminology glossary from the ComfyUI frontend (see [Terminology consistency](#terminology-consistency)) | | `npm run translate:review` | Score existing translations with an AI judge (see [Quality review](#quality-review)) | Pass extra flags after `--`: ```bash npm run translate -- --lang zh,ja npm run translate:dry-run -- --lang ja npm run translate -- installation/manual_install.mdx npm run translate:check-truncation -- --lang ko npm run translate:repair-truncated -- --lang ko ``` **Truncated translations** Long files can occasionally be cut off mid-translation (e.g. unclosed code fences). After a batch run, the script scans newly translated files and writes a repair list to `.github/i18n-logs/translate/truncation-issues.json` and `truncation-issues.txt` (gitignored). To scan everything for a language, or to repair: ```bash npm run translate:check-truncation -- --lang ko npm run translate:repair-truncated -- --lang ko ``` `repair-truncated` reads the JSON log and force re-translates only the flagged files. **How it works** - **Input**: English MDX (primary) + existing target-language file as context (if present) - **Output**: Updated files under `zh/`, `ja/`, `ko/`, etc., with refreshed `translationSourceHash` in frontmatter (snippets use an HTML comment for the hash) - **Review notes (mismatch)**: When the model reports semantic issues via `=== MISMATCHES ===`, they go to `.github/i18n-logs/translate/mismatches.json` and `mismatches.txt` (gitignored), not into MDX. Only produced during `npm run translate`, not by the truncation scanner. - **Truncation log**: Structural issues (unclosed code fences, short body) go to `.github/i18n-logs/translate/truncation-issues.json` — see [Truncated translations](#automated-translation) above. - **Skipped paths**: `built-in-nodes/` (configured in `translation-config.json` → `skip_paths`) - **Chunked files**: `changelog/index.mdx` is handled by `` version labels. The script compares EN vs target labels, translates only **missing** versions, and inserts them in EN order. Old blocks are never re-translated unless you use `--force`. - **Directories**: Subdirectories are created automatically when files are written; you do not need to `mkdir` by hand Script location: `.github/scripts/i18n/` (see `translate-i18n.ts`, `translation-config.json`, and the [i18n README](.github/scripts/i18n/README.md) for full details) #### Terminology consistency To keep the same English term rendered the same way across pages (e.g. avoid "custom node" drifting between two different Korean translations), three complementary mechanisms feed the translator. Each handles a different kind of term: | Mechanism | Effect | Example | Maintained | |-----------|--------|---------|------------| | `preserve_terms` (in `translation-config.json`) | keep the term **in English** | `checkpoint`, `LoRA`, `scheduler` | by hand | | `glossary/frontend/{lang}.json` | use the frontend's **translation** | `workflow → 워크플로` | machine-synced | | `glossary/overrides/{lang}.json` | **correct / extend** the frontend | `custom node → 커스텀 노드` | by hand, wins | The **ComfyUI frontend** ([`ComfyUI_frontend/src/locales`](https://github.com/Comfy-Org/ComfyUI_frontend/tree/main/src/locales)) is the authoritative source of term translations. `npm run glossary:sync` mirrors its locale terms into `glossary/frontend/{lang}.json` (rebuilt wholesale each run — never hand-edit). Hand-maintained corrections live in `glossary/overrides/{lang}.json`, which wins over the mirror and is the place to record a term decision or drop a noisy frontend term: ```jsonc // glossary/overrides/ko.json { "terms": { "custom node": "커스텀 노드" }, // remap or add (wins over frontend) "ignore": ["title", "additional", "work"] // drop a noisy frontend term } ``` At translation time, only terms that actually appear in a document are selected and injected as **preferred** (not mandatory) hints, so the model keeps natural phrasing when a literal substitution would read awkwardly. ComfyUI proper nouns with no settled translation (model names, `checkpoint`, …) instead go in `preserve_terms` to stay in English. See the [i18n README](.github/scripts/i18n/README.md) for the full design and curation guidance. ```bash npm run glossary:sync # rebuild the frontend mirror, all languages npm run glossary:sync -- --lang ko # one language npm run glossary:sync:dry-run # report counts without writing ``` The frontend locales source resolves in order: - **Remote (default):** `frontend_locales_url` in `translation-config.json` (GitHub raw `main` branch). Override with `FRONTEND_LOCALES_URL` or `--frontend-url `. - **Local (optional):** `--frontend ` or `FRONTEND_LOCALES_PATH` when you need an offline or forked checkout. #### Quality review `npm run translate:review` scores existing translations with an **independent** (and typically cheaper) AI model — an LLM-as-a-judge — on four axes: accuracy, completeness, terminology (checked against the glossary), and fluency. It is separate from the translation model's own `=== MISMATCHES ===` self-notes; here a different model acts as judge. Results are **advisory**: the detailed scores and issue list are written to `.github/i18n-logs/review/` (`quality-report.json` / `.txt`, gitignored) and never block a PR. The reviewed hash is recorded as `reviewSourceHash` in the translated file's frontmatter (committed to git), so review state is shared across the team and visible per file — mirroring `translationSourceHash`. By default only translations that are up to date with English and not yet reviewed at that hash are checked. ```bash npm run translate:review # pending reviews, all languages npm run translate:review -- --lang ko # one language npm run translate:review -- --all # re-review everything npm run translate:review -- --sample 20 # N pending files per language npm run translate:review -- --min-score 4 # report files scoring below 4/5 ``` Configure a dedicated cheap judge model via `REVIEW_API_KEY` / `REVIEW_API_BASE_URL` / `REVIEW_API_MODEL` in `.env.local` (falls back to the `TRANSLATE_*` model when unset). Use a fast model — evaluation is lighter than translation; reasoning-heavy models are slow under concurrency, so lower `REVIEW_CONCURRENCY` if you see connection errors. #### Adding a new language See [Request a new language](#adding-a-new-language) above — please open an issue rather than adding a language in a PR yourself. Maintainers: add one entry under `languages` in `.github/scripts/i18n/translation-config.json` (`code`, `name`, `dir`, `snippets_dir`). Path exclusion, link localization, and English-file scanning are derived automatically by `i18n-config.mjs` in the same folder — no per-language edits in translate scripts when adding a locale. Then add navigation in `docs.json` (see [Mintlify Localization](https://mintlify.com/docs/navigation/localization)), and batch-translate: ```bash npm run glossary:sync -- --lang fr # build the terminology glossary for the new locale npm run translate:dry-run -- --lang fr npm run translate -- --lang fr npm run translate:snippets -- --lang fr ``` The glossary is extended automatically: once the language is in `translation-config.json`, `npm run glossary:sync` generates `glossary/frontend/{lang}.json` from the ComfyUI frontend locale (provided the frontend ships that locale). An `glossary/overrides/{lang}.json` file is optional — add it later only to correct or pin specific terms. See [Terminology consistency](#terminology-consistency). #### Manual translation You can still translate by hand instead of using the script: 1. Create a file under the language directory with the **same filename and path** as the English original. 2. Localize `import` paths (`/snippets/...` → `/snippets/zh/...`) and internal links (`/path` → `/zh/path`). 3. Add the page path to the correct language group in `docs.json`. When English MDX changes, the `i18n-sync-check` workflow warns if matching translation files were not updated in the same PR, and posts a reminder comment tagging [@comfyui-wiki](https://github.com/comfyui-wiki). Update translations manually or re-run `npm run translate`. #### Contributing Workflow Examples When adding workflow examples to the documentation, please: 1. Take your output from ComfyUI (PNG, WebP), and add the models urls to the workflow so a user will have them when they drag in the workflow. You can use this [tool](https://comfyui-embeded-workflow-editor.vercel.app/) to edit the metadata of the PNG or WebP file. [](https://youtu.be/_zYbP8w7G8A) 2. Upload your workflow JSON and preview image to the [example_workflows repository](https://github.com/Comfy-Org/example_workflows) 3. Use the raw GitHub content URL in your documentation. To convert a GitHub file URL to a raw content URL: - Start with your GitHub file URL: ``` https://github.com/Comfy-Org/example_workflows/blob/main/your-workflow.json ``` - Change it to raw.githubusercontent.com and remove '/blob': ``` https://raw.githubusercontent.com/Comfy-Org/example_workflows/main/your-workflow.json ``` You can also click the "Raw" button on the GitHub file page and copy the URL directly. This ensures the workflow metadata is preserved in the docs site when dragging it into ComfyUI.