FaceFusion installation failures aren't random—they follow predictable patterns. Almost always, they come down to environment mismatches: incompatible Python versions, missing or misconfigured CUDA toolkits, and dependency conflicts within package managers like Conda or pip.
Because FaceFusion relies on GPU-accelerated inference through ONNX Runtime, any gap between your installed CUDA version, your Python interpreter, and the onnxruntime-gpu package tends to surface as cryptic errors during setup or first run.
What you might be experiencing
- "FaceFusion installation failed at step 7/12."
- "CUDA not detected even though I have an NVIDIA GPU."
- "pip install keeps failing with numpy errors."
- "Pinokio install worked once, now it just crashes."
- "I followed the tutorial exactly but it still doesn't work."
- "ModuleNotFoundError: No module named 'onnxruntime'"
- "The process cannot access this file because it is being used by another program."
If any of these sound familiar, you're hitting common installation issues.
When this happens most often
Installation failures cluster around several common scenarios:
-
First-time setup on Windows: If you don't have experience with Python environments, you might skip Conda environment creation or use a system-wide Python installation that conflicts with FaceFusion's requirements.
-
CUDA version mismatch: You have CUDA 12.x installed, but FaceFusion's onnxruntime-gpu builds often target CUDA 11.8. The mismatch causes silent failures or missing execution provider errors.
-
Pinokio-based installation: Pinokio simplifies setup, but it abstracts away environment details. When something goes wrong—interrupted downloads, VPN interference, pre-existing conflicting packages—you have limited visibility into what actually broke.
-
macOS with Apple Silicon: M1/M2/M3 users sometimes hit issues with dependencies like Cloudflared or with CoreML execution provider configuration.
-
Upgrading between major versions: Moving from FaceFusion 2.x to 3.x, or between 3.x minor versions, can introduce breaking changes in dependencies that require a clean environment rebuild.
Why this happens
FaceFusion's installation complexity comes from its architecture: a Python-based application that orchestrates multiple machine learning models through ONNX Runtime, with optional GPU acceleration via CUDA, TensorRT, OpenVINO, or CoreML.
1. Python version constraints
FaceFusion typically requires a specific Python version (commonly 3.10.x) for full compatibility. Using Python 3.11 or 3.12 may cause package resolution failures because some dependencies don't have pre-built wheels for newer Python versions yet.
2. The CUDA-ONNX Runtime alignment problem
ONNX Runtime GPU packages are compiled against specific CUDA versions. If your system has CUDA 12.4 but onnxruntime-gpu expects CUDA 11.8, the GPU execution provider silently fails to load, and FaceFusion either falls back to CPU (slow) or throws an error about missing providers.
3. Dependency tree conflicts
FaceFusion depends on packages like numpy, opencv-python, and various model-specific libraries. When these are installed in a shared environment (not an isolated Conda/venv), version conflicts pop up. A common symptom is numpy version errors—FaceFusion may need numpy < 2.0, but another package pulls in a newer version.
4. Launcher abstraction limits
Tools like Pinokio hide the underlying Conda/pip commands. This simplifies the happy path but makes debugging harder. If a download is interrupted, a package is partially installed, or a system-level conflict exists, the error messages are often opaque.
5. Platform-specific edge cases
- Windows: Long path issues, antivirus blocking executables, or missing Visual C++ redistributables
- Linux: Missing system libraries or permission issues in /tmp directories
- macOS: Rosetta translation issues on Apple Silicon, missing Xcode command-line tools, or Gatekeeper blocking unsigned binaries
Trade-offs you'll face
-
Pinokio vs manual installation: Pinokio offers one-click setup but sacrifices debuggability. Manual Conda installation requires more effort but gives you full control when things go wrong.
-
Latest CUDA vs stable CUDA: You might have the newest CUDA toolkit installed, but FaceFusion's tested configurations often lag behind. Using CUDA 11.8 with the matching onnxruntime-gpu version tends to be more stable than bleeding-edge setups.
-
Isolated environment vs system Python: Creating a dedicated Conda environment prevents conflicts but adds complexity. Using system Python is simpler initially but almost guarantees dependency collisions over time.
-
Frequent updates vs stability: FaceFusion releases updates regularly with new features, but upgrading without rebuilding the environment can introduce version mismatches.
Frequently asked questions
Q: Why doesn't CUDA appear as an option even though I have an NVIDIA GPU? A: The onnxruntime-gpu package may not match your installed CUDA version, or the CUDA toolkit isn't properly added to the system PATH. FaceFusion can't detect what the underlying runtime doesn't expose.
Q: Should I use Pinokio or manual installation? A: Pinokio is convenient if you want minimal setup. Manual installation via Conda is better if you need to troubleshoot or customize your environment.
Q: Why did installation work once but fail on reinstall? A: Residual files from previous installations can conflict with new ones. Incomplete uninstallation—especially of Conda environments or cached model files—often causes this.
Q: Does FaceFusion work on Mac? A: Yes, FaceFusion supports macOS, including Apple Silicon via CoreML. However, some dependencies may require additional configuration or Homebrew packages.
Q: Why do I get numpy version errors? A: FaceFusion may require numpy < 2.0, but other packages in the environment pull in numpy 2.x. Using an isolated environment with pinned dependency versions resolves this.
Related articles
- What FaceFusion Execution Providers Do and When They Fail – Understanding CUDA vs OpenVINO vs CoreML selection
- FaceFusion on Google Colab – Cloud-specific installation and runtime problems
- Face Swap Troubleshooting Hub – Central diagnostic index for all face swap issues
Final thoughts
FaceFusion installation failures are frustrating but predictable. They almost always trace back to environment configuration—Python version, CUDA version, or dependency conflicts. Understanding that FaceFusion isn't a standalone application but a Python package with strict runtime requirements helps set realistic expectations. The path of least resistance is an isolated Conda environment with known-good versions of Python (3.10.x) and CUDA (11.8), rather than trying to fit FaceFusion into an existing, cluttered Python setup.