faceswap 安装与环境配置指南：硬件前提、手动安装流程与多后端依赖解析

2026-09-06 20:58:06作者：俞予舒Fleming

本篇指南基于 faceswap 仓库的 INSTALL.md 完整展开，覆盖从硬件与操作系统前提、官方安装器、Anaconda 虚拟环境搭建，到 python setup.py 一键安装与按 GPU 后端（NVIDIA CUDA / AMD ROCm / CPU / Apple Silicon）选择依赖文件的全部实操步骤；并结合 setup.py、requirements/requirements.py 等源码，解释安装脚本如何检测后端、校验版本并把配置落盘，帮助你在 Linux、Windows 或 macOS 上把 faceswap 完整部署并跑起来。

一、前提：硬件要求与操作系统支持

faceswap 的模型训练本质上是让程序尝试数百万种参数组合以逼近目标效果，这类计算非常适合 GPU 并行处理，而普通 CPU 上训练一个模型可能需要数周、GPU 上则只需数小时。文档明确强调：几乎必须在一台配备桌面级或服务端级 GPU 的机器上运行训练流程。

1.1 硬件要求（TL;DR：至少满足其一）

较强的 CPU：笔记本 CPU 通常可以运行本软件，但速度不足以支撑合理周期的训练。
较强的 GPU：
- NVIDIA GPU：全面支持；需至少支持 CUDA Compute Capability 3.5（Release 1.0 可下探到 3.0）。桌面端 7xx 系列之后的显卡大概率受支持。
- AMD GPU：较新型号在 Linux 上通过 ROCm 支持。
- Apple M 系列芯片：通过 Metal 支持。
大量耐心：文档原话。

1.2 受支持的操作系统

系统	说明
Windows 10/11	Windows 7/8 在 NVIDIA 环境下“可能可用”。官方提供 Windows 安装器（installer），可自动完成全部环境配置
Linux	大多数 Ubuntu/Debian 或 CentOS 系发行版可用。官方提供 Linux 安装脚本，一键装好依赖
macOS	实验性支持 Apple Silicon（如 M1）原生 GPU 加速；Intel Mac 理论上可用，但需走下文的手动安装流程
通用	所有操作系统必须是 64 位

从源码结构看，仓库内 .install/ 目录下按 linux、macos、windows 三个子目录组织各平台安装器的构建材料，对应文档中“Windows、Linux 和 macOS 均有安装器”的说法。若你不需要手动折腾，直接从官方 Releases 页面下载对应安装器是最省事的路径；本文其余内容面向安装器失败或想完全掌控环境的用户。

1.3 开始前的注意事项

文档特别指出：当前版本的 faceswap 仍然高度依赖命令行操作（虽然有 GUI 可用）。如果你不熟悉命令行工具，环境配置过程可能会比较困难。该文档假定读者具备中等水平的命令行知识，且开发者不对因安装操作对电脑造成的损坏负责。

二、Windows / Linux / macOS 通用安装流程（手动安装）

文档建议“尽可能在 Linux 上使用”——Windows 大约会占用 20% 的显存，使 faceswap 略慢，但 Windows 完全被 100% 支持。

2.1 前置软件：Anaconda 与 Git

Anaconda：下载并安装最新版 Python 3 的 Anaconda，除非你清楚自己在做什么，否则所有安装选项保持默认。
Git：下载并安装 Git（Windows 可从 git-scm 官网下载），选项保持默认。
重启电脑，让刚安装的程序完成注册。

2.2 用 Anaconda Navigator 创建并进入虚拟环境

创建虚拟环境：

打开 Anaconda Navigator，在左侧选择 “Environments”；
点击底部 “Create”；
在弹窗中命名为 faceswap；
重要：Python 版本选择 3.13；
点击 “Create”（需要下载 Python，可能耗时较久）。

进入虚拟环境：

打开 Anaconda Navigator → 左侧 “Environments”；
点击 faceswap 环境旁的 “>” 箭头，选择 “Open Terminal”。

2.3 获取代码并运行 Easy Install

确认已进入虚拟环境后：

git clone --depth 1 https://github.com/deepfakes/faceswap.git
cd faceswap

随后执行一键安装：

python setup.py

并跟随提示操作。若出现错误或问题，则继续下文的 Manual install。

setup.py 并不是一个简单的 pip 包装脚本。从源码可以看到它的工作流程（见 setup.py 末尾的 __main__ 段，setup.py#L918-L927）：

Environment()：解析运行系统（操作系统、是否 Conda、是否虚拟环境、编码），并解析命令行参数确定后端（nvidia / apple_silicon / rocm / cpu）与对应的 requirements 文件版本；
Checks()：交互式提问（CUDA 或 ROCm 二选一及版本号）、检测全局安装的 CUDA/cuDNN/ROCm 并给出提示；
ENV.set_config()：把选定的 backend 写入 config/.faceswap，并把 Keras 的 keras.json 后端设为 torch；
Install()：比对已装包与目标版本，通过 conda/pip 安装缺失依赖，失败时退出码为 1 并指向日志。

几个值得注意的实现细节：

Apple Silicon 自动识别：_process_arguments() 中（setup.py#L154-L156）检测到 macOS + arm64 时直接固定 backend 为 apple_silicon、requirements 为 apple-silicon，无需任何交互；
命令行可直接指定后端：_parse_backend_from_cli()（setup.py#L113-L144）会扫描 sys.argv 中以 -- 开头的参数，形如 --nvidia_13、--rocm_64、--cpu；只给 --nvidia 时默认取该后端最新的 requirements 文件；
交互式版本选择：在 Linux/Windows 上若未指定后端，脚本会依次询问 Enable ROCm Support? [y/N]（选择 ROCm 后追问版本 6.0–6.4）与 Enable CUDA? [Y/n]，再询问 Which Cuda version: 11 (GTX7xx-8xx), 12 (GTX9xx-10xx) or 13 (RTX20xx-)?（setup.py#L396-L442）。这与 requirements/ 目录中的文件名一一对应。

2.4 Manual Install：按 GPU 后端选择 requirements 文件

仅当 Easy Install 未成功完成时才需要本节。若使用 NVIDIA 卡，请确保为你的 Torch 版本安装了对应版本的 Cuda/cuDNN。

第一步：安装 tkinter（GUI 依赖）：

conda install tk

第二步：按硬件选择 requirements 文件安装 Python 依赖（均在 faceswap 目录内执行）：

硬件/后端	命令	备注
NVIDIA（RTX 20xx 及以后）	`pip install -r ./requirements/requirements_nvidia_13.txt`	CUDA 13 系列
NVIDIA（GTX 9xx – GTX 10xx）	`pip install -r ./requirements/requirements_nvidia_12.txt`	CUDA 12 系列
NVIDIA（GTX 7xx – GTX 8xx）	`pip install -r ./requirements/requirements_nvidia_11.txt`	GTX 8xx–9xx 支持的最高 Python 版本为 3.13
AMD（仅 Linux，ROCm 6.4）	`pip install -r ./requirements/requirements_rocm64.txt`	需先安装与系统/GPU 兼容的 ROCm
AMD（ROCm 6.3）	`pip install -r ./requirements/requirements_rocm63.txt`	ROCm 6.1–6.2 支持的最高 Python 版本为 3.13
AMD（ROCm 6.2）	`pip install -r ./requirements/requirements_rocm62.txt`	同上
AMD（ROCm 6.1）	`pip install -r ./requirements/requirements_rocm61.txt`	同上
AMD（ROCm 6.0）	`pip install -r ./requirements/requirements_rocm60.txt`	ROCm 6.0 支持的最高 Python 版本为 3.12
纯 CPU	`pip install -r ./requirements/requirements_cpu.txt`	可运行但训练很慢
Apple Silicon（M 系列）	`pip install -r ./requirements/requirements_apple-silicon.txt`	配合下文 macOS 专用步骤

对照仓库实际文件，requirements/ 目录中还额外提供了 requirements_rocm_71.txt 与 requirements_rocm_72.txt，说明仓库已包含面向更新 ROCm 版本（7.1/7.2）的依赖定义，只是 INSTALL.md 与 setup.py 的交互式提问目前仍以 6.0–6.4 为选项列表。

以 requirements/requirements_nvidia_13.txt 为例，其内容非常短小，但揭示了版本矩阵的设计：

# Cuda compatibility 7.5-
# RTX 20xx -
-r _requirements_base.txt
# Exclude badly numbered Python2 version of nvidia-ml-py
nvidia-ml-py>=12.535,<300
--extra-index-url https://download.pytorch.org/whl/cu130
torch>=2.9.0,<2.13.0

即：各后端的 requirements 文件都通过 -r 引入公共的 _requirements_base.txt，再叠加该后端特有的 PyTorch 索引源与版本约束。公共基座依赖（当前版本）包括 packaging、tqdm、psutil、numexpr、numpy>=2.4.0,<2.5.0（有注释说明 numpy 2.5.x 与 alignments 反序列化的兼容问题）、opencv-python、pillow、scikit-learn、fastcluster、matplotlib、av、ffmpeg-binaries、ffmpy、Windows 下的 pywin32、torchvision、tensorboard、keras>=3.14.1,<3.15.0 等——覆盖了图像处理、聚类、视频解码与训练可视化的全部基础能力。

版本上限的校验逻辑在 requirements/requirements.py：PYTHON_VERSIONS 字典记录各 requirements 文件的“最高支持 Python 版本”（如 rocm_60 对应 (3, 12)），Environment.set_requirements() 在设置 requirements 时会调用 system.validate_python(max_version=...) 拦截过新的解释器（setup.py#L99-L111）。

2.5 运行 faceswap

确认已进入虚拟环境后：

cd faceswap
python faceswap.py -h     # 查看全部子命令与选项
python faceswap.py gui    # 启动图形界面

从入口源码看，faceswap.py 的 _main()（faceswap.py#L37-L57）会先调用 generate_configs() 生成配置文件，然后注册四个子命令：extract（从图片/视频中提取人脸）、train（训练 A/B 两个脸的模型）、convert（将源图片/视频转换为换脸结果）与 gui（启动 GUI）；参数非法时打印帮助并退出。安装成功后，脚本结束日志也会提示这两条命令（setup.py#L882-L884）。

三、创建桌面快捷方式（Windows）

可以在桌面放一个 .bat 快捷方式直接启动 GUI：

打开记事本；
粘贴以下内容：

%USERPROFILE%\Anaconda3\envs\faceswap\python.exe %USERPROFILE%/faceswap/faceswap.py gui

保存为桌面上的 faceswap.bat。

四、更新 faceswap

新功能与修复会持续加入，建议保持更新。两种方式：

GUI 内更新：Help 菜单 → “Check for Updates...”，如有更新再选 “Update Faceswap”，完成后重启 Faceswap。
命令行更新（确认在虚拟环境中）：

cd faceswap
git pull --all
python update_deps.py

从源码看，update_deps.py 复用 setup.py 中的 Environment(updater=True) 与 Install：Environment 以 updater 模式构造时会跳过部分系统校验，并自动用 lib.utils.get_backend() 读取当前已配置的 backend 作为安装目标，再增量补齐缺失依赖——这正是它与完整 setup.py 共用的核心逻辑（setup.py#L146-L153、setup.py#L785-L789 中对 updater 的分支处理）。

五、macOS（Apple Silicon）专用安装指南

macOS 如今也有官方安装器；若遇到问题需手动配置，步骤如下。

前提：

OS：macOS 12.0 及以上；
XCode 命令行工具：

xcode-select --install

XQuartz：从 XQuartz 官网下载安装（GUI 的 X 窗口依赖）；
Conda：下载 conda-forge 的 Miniforge ARM64 安装脚本（Miniforge3-MacOSX-arm64.sh）并安装：

$ chmod +x ~/Downloads/Miniforge3-MacOSX-arm64.sh
$ sh ~/Downloads/Miniforge3-MacOSX-arm64.sh
$ source ~/miniforge3/bin/activate

创建并激活环境：

$ conda create --name faceswap python=3.13
$ conda activate faceswap

获取代码并安装：

$ git clone --depth 1 https://github.com/deepfakes/faceswap.git
$ cd faceswap
$ python setup.py

Easy install 失败时，参照 2.4 节手动安装 requirements/requirements_apple-silicon.txt。注意 setup.py 在 arm64 macOS 上会自动选定 Apple Silicon 后端（setup.py#L154-L156），Checks 阶段对 apple_silicon 也直接跳过交互提问（setup.py#L387-L389），因此该路径下基本无交互。

六、通用安装指南（General Install Guide）

除上述分平台指南外，INSTALL.md 还给出了一套通用流程与要点：

1. 安装依赖三件套

Git：获取代码与保持代码库更新所必需，从 Git 官网获取对应发行版的安装包；
Python：文档推荐的做法是使用 Conda3 环境，这样 NVIDIA 的 CUDA 与 cuDNN 会被直接装入你的 Conda 环境，是“最省事也最可靠”的路径，其中推荐 MiniConda3。作为替代，也可以为发行版安装 Python（文档中给出的通用路线示例为 3.14 64 位，Linux 可用 apt/yum install python3、Windows 用官方安装器、macOS 用 Homebrew 的 python3）；走这条路线且使用 NVIDIA GPU 时，需要自行安装 CUDA 与 cuDNN，并确保其版本与当前安装的 Torch 匹配；
虚拟环境：强烈建议把 faceswap 装进虚拟环境。文档明确指出：通常不会为不位于虚拟环境中的安装提供支持，因为包冲突的排障几乎不可能。Conda3 下建虚拟环境很直接；使用系统 Python 时可借助 virtualenv 与 virtualenvwrapper。

2. 获取代码：文档推荐用 git clone 而非下载压缩包，因为这样更容易从 GUI 内获取最新代码：

git clone https://github.com/deepfakes/faceswap.git

3. 配置：进入虚拟环境与 faceswap 目录后执行 python setup.py；若 setup 因任何原因失败，仍然可以手动安装 requirements 文件夹内列出的包。

4. 选项说明

CUDA：用于加速，需要支持 CUDA 的优质 NVIDIA 显卡；
ROCm：仅限 Linux/WSL2 上的 AMD GPU，注意为你的 ROCm 版本安装正确版本的 faceswap 依赖。

七、运行项目与问题排查

安装完成后即可尝试运行 faceswap 工具，用 -h 或 --help 查看全部选项：

python faceswap.py -h

或：

python faceswap.py gui

排查要点（结合源码）：

setup.py 运行时会把日志写入项目根目录的 faceswap_setup.log（setup.py#L919-L920 的 log_setup 调用），任何包安装失败都会在该日志中记录，并以退出码 1 结束，同时提示“可手动安装这些包”；
Checks 阶段检测到全局安装的 CUDA/cuDNN/ROCm 时，会提示“PyTorch 自带其 CUDA 版本，如遇 GPU 问题应移除这些全局安装”（setup.py#L451-L508），这类警告会在安装开始前的确认提示中一并打印；
backend 的最终生效位置是 config/.faceswap（Environment.set_config() 写入，setup.py#L216-L224）；运行时 lib/utils.py 的 get_backend() 会优先读取环境变量 FACESWAP_BACKEND，其次读取该配置文件（lib/utils.py#L44-L80），这也是 python setup.py 之后各子命令能找到正确推理后端的原因；
文档在 Notes 中提醒：该指南远非完备，功能会随时间变化、依赖会增删；如遇问题，请到 faceswap 官方论坛反馈，而不是直接在主仓库开 issue——仓库中提出的用法类 issue 很可能不回复就被关闭。

安装完成后的下一步是了解 extract → train → convert 的工作流程与 GUI 使用，可继续阅读 USAGE.md。

八、要点速查

场景	关键动作
想最省事	下载官方平台安装器（Windows/Linux/macOS 均有）
手动安装	Anaconda + Git → 建 `faceswap` 环境（Python 3.13）→ `git clone --depth 1` → `python setup.py`
Easy 安装失败	按 2.4 节表格选择对应 `requirements/requirements_*.txt` 手动 `pip install -r`
Apple Silicon	Miniforge arm64 + `conda create --name faceswap python=3.13`，`setup.py` 自动选 Apple Silicon 后端
运行	`python faceswap.py -h` 查看子命令；`python faceswap.py gui` 启动 GUI
更新	GUI 的 Help 菜单，或 `git pull --all` + `python update_deps.py`
排障	查看 `faceswap_setup.log`；确认处于虚拟环境；按 `Checks` 的警告清理全局 CUDA/cuDNN