> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-recommend-assets-api.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# macOS 桌面版
> 本文将介绍 ComfyUI Desktop macOS 版本的下载以及安装使用。
export const log_path_0 = "~/Library/Logs/ComfyUI"
export const config_path_0 = "~/Library/Application Support/ComfyUI"
**ComfyUI 桌面版（Desktop）** 是一个独立的安装版本，可以像常规软件一样安装，支持快捷安装、自动配置 **Python 环境及依赖**，并支持导入已有的 ComfyUI 设置、模型、工作流和文件。
ComfyUI 桌面版是一个开源项目，完整代码请访问[这里](https://github.com/Comfy-Org/desktop)。
ComfyUI 桌面版（macOS）目前仅支持 Apple Silicon。
本篇教程将引导你完成对应的软件安装，并提供相关的安装配置说明。
由于 **ComfyUI 桌面版** 仍处于 **Beta** 状态，实际的安装过程可能会发生变化。
## ComfyUI 桌面版（macOS）下载
请点击下面的按钮下载对应的 macOS 系统 **ComfyUI 桌面版** 安装包。
Download for macOS
## 通过 Homebrew 安装
ComfyUI 桌面版也可通过 [Homebrew](https://brew.sh/) 安装：
```
brew install comfyui
```
## ComfyUI 桌面版安装步骤
1. 双击下载到的安装包文件。
2. 如图所示，请将 **ComfyUI** 程序按箭头所示拖入 **Applications** 文件夹。
3. 如果在打开安装包后，文件夹显示如下（图标上出现禁止符号），则说明你当前的系统版本与 **ComfyUI 桌面版** 不兼容。
4. 然后在 **启动台 (Launchpad)** 中找到对应的 **ComfyUI 图标**，点击它即可进入 ComfyUI 的初始化设置。
## ComfyUI 桌面版初始化流程
点击 **Get Started** 开始初始化步骤。
安装 ComfyUI 可能会出现许多问题。也许在安装 pytorch（15 GB）时网络连接失败，或者你没有安装 git，当检测到问题时，维护页面会自动打开，并提供解决问题的方法。
你可以使用它来解决大多数问题：
* 创建一个 Python 虚拟环境
* 重新安装所有缺失的核心依赖项到由桌面管理的 Python 虦虚拟环境
* 安装 git，VC redis
* 选择一个新的安装位置
默认维护页面会显示当前报错的内容
点击 `All` 可以切换查看可以操作的所有内容
对应三个选项：
1. **MPS（推荐）：** Metal Performance Shaders (MPS) 是苹果的优化框架，让开发者能在苹果设备上利用 GPU 加速包括机器学习在内的高性能计算任务，且支持 PyTorch 等框架使用 GPU 提升模型训练和推理效率。
2. **Manual Configuration（手动配置）：** 你需要手动安装和配置 Python 运行环境。除非你知道应该如何配置，否则请不要选择。
3. **Enable CPU Mode（启用 CPU 模式）：** 仅适用于开发人员和特殊情况。除非你确定需要使用此模式，否则请不要选择。
如无特殊情况，请按截图所示选择 **MPS**，然后点击 **Next** 进入下一步。
在这一步选择 ComfyUI 以下相关内容的安装位置：
* **Python 环境**
* **Models（模型文件）**
* **Custom Nodes（自定义节点）**
建议：
* 请新建一个单独的空白文件夹作为 ComfyUI 的安装目录。
* 请确保磁盘至少有 **5GB** 左右的可用空间，以保证 **ComfyUI 桌面版** 的正常安装。
ComfyUI 并非所有文件都安装在此目录下，部分文件将会位于 macOS 的系统目录下。你可以参考本篇指南的卸载部分，了解如何完全卸载 ComfyUI 桌面版。
完成后点击 **Next** 进入下一步。
在这一步，你可以将已有的 ComfyUI 安装内容迁移到 ComfyUI 桌面版中。选择你电脑上已有的 **ComfyUI** 安装目录，安装程序会自动识别对应目录下的：
* **User Files（用户文件）**
* **Models（模型文件）：** 不会进行复制，只是与桌面版进行关联。
* **Custom Nodes（自定义节点）：** 节点将会重新进行安装。
不用担心，此步骤不会复制模型文件。你可以按需勾选或取消勾选对应的选项，然后点击 **Next** 进入下一步。
这一步是偏好设置：
1. **Automatic Updates（自动更新）：** 设置是否在 ComfyUI 更新可用时自动更新。
2. **Usage Metrics（使用情况分析）：** 如果启用，我们将收集**匿名的使用数据**，用于帮助我们改进 ComfyUI。
3. **Mirror Settings（镜像设置）：** 由于程序需要联网下载 Python 以完成相关环境安装，如果你在安装时也如图所示出现红色的 ❌，这可能导致后续安装失败。请参考下面步骤进行处理：
展开对应的镜像设置，找到具体失败的镜像。在当前截图中，错误为 **Python Install Mirror** 镜像下载失败。
对于不同的镜像错误，你可以参考下面的内容尝试手动查找不同的镜像，并进行替换
以下情况主要针对中国境内用户
#### Python 安装镜像
如果默认镜像无法使用，请尝试使用下面的镜像
```
https://python-standalone.org/mirror/astral-sh/python-build-standalone
```
如果你需要查找其它备选 GitHub 的镜像地址，请查找并构建指向 `python-build-standalone` 仓库releases的镜像地址
```
https://github.com/astral-sh/python-build-standalone/releases/download
```
构建类似下面格式的链接
```
https://xxx/astral-sh/python-build-standalone/releases/download
```
由于大多 Github 镜像服务都由第三方提供，所以请注意使用过程中的安全性。
#### PyPI 镜像
* 阿里云：[https://mirrors.aliyun.com/pypi/simple/](https://mirrors.aliyun.com/pypi/simple/)
* 腾讯云：[https://mirrors.cloud.tencent.com/pypi/simple/](https://mirrors.cloud.tencent.com/pypi/simple/)
* 中国科技大学：[https://pypi.mirrors.ustc.edu.cn/simple/](https://pypi.mirrors.ustc.edu.cn/simple/)
* 上海交通大学：[https://pypi.sjtu.edu.cn/simple/](https://pypi.sjtu.edu.cn/simple/)
#### Torch 镜像
* 阿里云: [https://mirrors.aliyun.com/pytorch-wheels/cu121/](https://mirrors.aliyun.com/pytorch-wheels/cu121/)
如果一切无误，安装程序将完成安装并自动进入 ComfyUI 桌面版界面，这说明已经安装成功。
## 重要提示：请勿修改 resource/ComfyUI 文件夹
请勿在 `/resource/ComfyUI` 文件夹中添加或修改任何内容。此文件夹中的所有内容将在 ComfyUI 桌面版更新时被重置。
与其他 ComfyUI 版本不同，桌面版会自动管理此文件夹。在安装过程中，你已选择了模型、自定义节点和其他用户文件的自定义存储位置，请使用该位置存放你的文件。
## 进行第一次图片生成
安装成功后，你可以参考访问下面的章节，开始你的 ComfyUI 之路。
本教程将引导你完成第一次的模型安装以及对应的文本到图片的生成
## 如何更新 ComfyUI 桌面版
目前 ComfyUI 桌面版更新采用自动检测更新，请确保在设置中已经启用自动更新
你也可以在 `菜单` --> `帮助` --> `检查更新` 中选择手动检查是否有可用的更新
## 添加外部模型路径
如果你想要在 `ComfyUI/models` 之外管理你的模型文件，可能出于以下原因:
* 你有多个 ComfyUI 实例，你想要让这些实例共享模型文件，从而减少磁盘占用
* 你有多个不同的类型的 GUI 程序，如：WebUI, 你想要他们共用模型文件
* 模型文件无法被识别或读取到
我们提供了通过 `extra_model_paths.yaml` 配置文件来添加额外模型搜索路径的方法。
### 不同 ComfyUI 版本配置文件位置
对于[便携版](/zh/installation/comfyui_portable_windows)和[手动安装](/zh/installation/manual_install)的 ComfyUI版本，你可以在 ComfyUI 的根目录下找到 `extra_model_paths.yaml.example` 的示例文件
```
ComfyUI/extra_model_paths.yaml.example
```
复制并重命名为 `extra_model_paths.yaml` 来使用, 并保持在 ComfyUI 的根目录下, 路径应该是 `ComfyUI/extra_model_paths.yaml`
你也可以在 [这里](https://github.com/comfyanonymous/ComfyUI/blob/master/extra_model_paths.yaml.example) 找到配置示例文件
如果你使用的是 ComfyUI 桌面应用程序，你可以参考下图打开额外模型的配置文件：
或者通过下面的位置打开：
```
C:\Users\YourUsername\AppData\Roaming\ComfyUI\extra_models_config.yaml
```
```
~/Library/Application Support/ComfyUI/extra_models_config.yaml
```
对应的配置文件不应该被改变
### 配置示例
比如，你需要额外让 ComfyUI 识别的模型文件位于下面的文件夹:
```
📁 YOUR_PATH/
├── 📁models/
| ├── 📁 loras/
| │ └── xxxxx.safetensors
| ├── 📁 checkpoints/
| │ └── xxxxx.safetensors
| ├── 📁 vae/
| │ └── xxxxx.safetensors
| └── 📁 controlnet/
| └── xxxxx.safetensors
```
那么你可以进行如下的配置来让 ComfyUI 识别到你设备上的模型路径
```
my_custom_config:
base_path: YOUR_PATH
loras: models/loras/
checkpoints: models/checkpoints/
vae: models/vae/
controlnet: models/controlnet/
```
或者使用
```
my_custom_config:
base_path: YOUR_PATH/models/
loras: loras
checkpoints: checkpoints
vae: vae
controlnet: controlnet
```
对于桌面版，请在原有配置路径下新增配置，而不覆盖掉安装过程中自动生成的路径配置，请在修改前备份对应的文件，这样在你配置错误时可以及时恢复
或者你也可以参考默认的 [extra\_model\_paths.yaml.example](https://github.com/comfyanonymous/ComfyUI/blob/master/extra_model_paths.yaml.example) 来配置，保存之后， 需要 **重启 ComfyUI** 才能生效。
下面是完整的原始的配置配置示例:
```yaml theme={null}
#Rename this to extra_model_paths.yaml and ComfyUI will load it
#config for a1111 ui
#all you have to do is change the base_path to where yours is installed
a111:
base_path: path/to/stable-diffusion-webui/
checkpoints: models/Stable-diffusion
configs: models/Stable-diffusion
vae: models/VAE
loras: |
models/Lora
models/LyCORIS
upscale_models: |
models/ESRGAN
models/RealESRGAN
models/SwinIR
embeddings: embeddings
hypernetworks: models/hypernetworks
controlnet: models/ControlNet
#config for comfyui
#your base path should be either an existing comfy install or a central folder where you store all of your models, loras, etc.
#comfyui:
# base_path: path/to/comfyui/
# # You can use is_default to mark that these folders should be listed first, and used as the default dirs for eg downloads
# #is_default: true
# checkpoints: models/checkpoints/
# clip: models/clip/
# clip_vision: models/clip_vision/
# configs: models/configs/
# controlnet: models/controlnet/
# diffusion_models: |
# models/diffusion_models
# models/unet
# embeddings: models/embeddings/
# loras: models/loras/
# upscale_models: models/upscale_models/
# vae: models/vae/
#other_ui:
# base_path: path/to/ui
# checkpoints: models/checkpoints
# gligen: models/gligen
# custom_nodes: path/custom_nodes
```
### 添加额外自定义节点路径
除了添加外部模型之外，你同样可以添加不在 ComfyUI 默认路径下的自定义节点路径
请注意，这并不会改变自定义节点的默认安装路径，只是在启动 ComfyUI 时会增加额外的路径搜索，你仍旧需要在对应的环境中完成自定义节点的依赖的安装，来保证其运行环境的完整性。
下面是一个简单的配置示例（Mac 系统），请根据你的实际情况进行修改，并新增到对应的配置文件中，保存后需要 **重启 ComfyUI** 才能生效:
```yaml theme={null}
my_custom_nodes:
custom_nodes: /Users/your_username/Documents/extra_custom_nodes
```
## 桌面端 Python 环境相关
桌面端的安装将在你选择的安装目录下创建一个python 的虚拟环境，通常这是一个隐藏的 `.venv` 文件夹。
如果你需要为 ComfyUI 插件处理相关的依赖则需要在这个环境中进行处理，直接系统系统的命令行会有将对应依赖安装到系统环境的风险，请参考下面的指示完成对应环境的激活。
### 如何使用 桌面端 的 python 环境？
你可以使用桌面端自带的终端来使用 python 环境。
1. 点击菜单栏的 icon 打开底部面板
2. 点击 `Terminal` 打开终端
3. 如果你想要看对应环境的 python 安装位置，可以使用下面的命令
```
python -c "import sys; print(sys.executable)"
```
```
which python
```
除非你了解你当前的操作含义，否则你的操作可能会导致对应环境依赖的问题，请谨慎使用此方式进行操作
你也可以使用你喜欢的终端来使用 python 环境，但在使用之前需要先激活对应的虚拟环境。
在使用其它终端进行操作时，如果你不熟悉相关操作，可能会将对应依赖安装到系统环境，请谨慎使用此方式进行操作
在截图中，是一个 macOS 终端的示例。如果你使用的是 Windows，请参考以下步骤在系统上激活虚拟环境。
打开你喜欢的终端，使用 `cd` 命令进入你安装的 ComfyUI 的目录如
```
cd <你的 ComfyUI 安装目录>/ComfyUI
```
在终端中输入下面的命令激活虚拟环境
```
.venv/Scripts/activate
```
```
source .venv/bin/activate
```
激活后，你可以在终端中看到类似 `(ComfyUI)` 的提示，表示你已经激活了虚拟环境
使用 `which python` 查看当前 python 所在环境，确认不是系统环境
完成以上步骤后你就激活了对应的 Python 环境，你可以继续在这个环境里进行依赖安装相关的操作了。
## 如何卸载 ComfyUI 桌面版
要卸载 **ComfyUI 桌面版**，你可以直接在 **Applications** 文件夹内删除 **ComfyUI** 程序。
如果你想要**完全删除** **ComfyUI 桌面版** 的所有文件，可以手动删除以下文件夹：
```
~/Library/Application Support/ComfyUI
```
以上操作**不会**删除你的以下文件夹。如果需要，请手动删除：
* Models（模型文件）
* Custom Nodes（自定义节点）
* Input/Output 目录（图片输入/输出目录）
## 故障排除
### 如何定位安装错误
如果安装失败，你应该可以看到下面的界面显示
此时建议你采取以下几种方式查找错误原因
1. 点击 `Show Teriminal` 查看错误问题输出
2. 点击 `Open Logs` 查看安装过程日志
3. 访问官方论坛查找错误反馈
4. 点击`Reinstall`尝试重新安装
建议在提交反馈之前，你可以将对应的**错误输出**以及 **log 文件**信息提供给类似 **GPT**一类的工具
如上图，询问对应错误的原因，或者完全删除 ComfyUI 后进行安装重试
### 反馈错误
如果在安装过程中，你发生了任何错误，请通过以下任意方式查看是否有类似错误反馈，或者向我们提交错误
* Github Issues: [https://github.com/Comfy-Org/desktop/issues](https://github.com/Comfy-Org/desktop/issues)
* Comfy 官方论坛: [https://forum.comfy.org/](https://forum.comfy.org/)
请在提交错误时确保提交了以下日志以及配置文件，方便我们进行问题的定位和查找
1. 日志文件
| 文件名 | 描述 | 位置 |
| ----------- | ------------------------------------------- | ------------ |
| main.log | 包含与桌面应用和服务器启动相关的日志，来自桌面的 Electron 进程。 | {log_path_0} |
| comfyui.log | 包含与 ComfyUI 正常运行相关的日志，例如核心 ComfyUI 进程的终端输出。 | {log_path_0} |
2. 配置文件
| 文件名 | 描述 | 位置 |
| ------------------------ | ---------------------------- | --------------- |
| extra\_model\_paths.yaml | 包含 ComfyUI 将搜索模型和自定义节点的额外路径。 | {config_path_0} |
| config.json | 包含应用配置。此文件通常不应直接编辑。 | {config_path_0} |
