Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hacksider/Deep-Live-Cam/llms.txt

Use this file to discover all available pages before exploring further.

Most Deep-Live-Cam installation problems fall into a small number of categories: a missing system dependency (ffmpeg, Python 3.11), the wrong onnxruntime variant for your hardware, a missing or misplaced model file, or a macOS-specific package conflict. Work through the accordion below that matches your error message. If you are on macOS, read the macOS-specific entries as well — several issues only affect Apple Silicon setups.
Deep-Live-Cam calls ffmpeg directly for all video operations and will refuse to start if it cannot find the binary on your PATH. Confirm whether ffmpeg is installed by running:
ffmpeg -version
If the command is not found, install ffmpeg for your platform:
Run the one-liner from the README in a PowerShell terminal:
iex (irm ffmpeg.tc.ht)
After installation, open a new terminal and run ffmpeg -version to confirm it is on your PATH.
After installing, open a new terminal session so the updated PATH takes effect, then retry ffmpeg -version.
Deep-Live-Cam requires Python 3.11. Versions below 3.9 are rejected at startup, and newer versions such as 3.13 are not compatible with some compiled dependencies.Check your active Python version:
python --version
If the output is not Python 3.11.x, install Python 3.11 from python.org/downloads or via your package manager.On macOS, if multiple Python versions are installed via Homebrew, call the version explicitly:
python3.11 --version
Always create your virtual environment with python3.11 on macOS to avoid picking up the wrong interpreter:
python3.11 -m venv venv
source venv/bin/activate
If you see an error like ModuleNotFoundError: No module named '_tkinter' when launching the GUI on macOS, the Homebrew tkinter binding for Python 3.11 is missing or broken.Reinstall it with:
brew reinstall python-tk@3.11
Then recreate your virtual environment to pick up the updated library:
deactivate
rm -rf venv
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
Deep-Live-Cam requires two ONNX model files to be present in the models/ folder inside the repository before the application starts:
  • GFPGANv1.4.onnx
  • inswapper_128_fp16.onnx
Verify the files are in place:
ls models/
Expected output:
GFPGANv1.4.onnx
inswapper_128_fp16.onnx
If either file is missing, download it from the HuggingFace repository and place it in the models/ folder:
All available models are listed at huggingface.co/hacksider/deep-live-cam.
Each hardware acceleration backend requires a specific onnxruntime variant. Installing the wrong variant (or leaving a conflicting one installed) causes the GPU provider to be silently skipped or to raise an import error.Uninstall any existing onnxruntime packages first, then install the correct one for your hardware:
pip uninstall onnxruntime onnxruntime-gpu
pip install onnxruntime-gpu==1.21.0
After installing the correct variant, launch with the matching --execution-provider flag, for example --execution-provider cuda.
CUDA errors at runtime typically mean one of three things: CUDA Toolkit is not installed, the version does not match what onnxruntime-gpu expects, or the cuDNN binaries are not on your PATH.Deep-Live-Cam requires:After installing cuDNN, add its bin directory to your system PATH. On Windows this is typically C:\Program Files\NVIDIA\CUDNN\v8.9\bin. On Linux, add the directory to LD_LIBRARY_PATH:
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH
Then install the CUDA-compatible PyTorch and onnxruntime-gpu builds:
pip install -U torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
pip uninstall onnxruntime onnxruntime-gpu
pip install onnxruntime-gpu==1.21.0
Launch with:
python run.py --execution-provider cuda
If the live face swap runs below acceptable frame rates, try the following adjustments in order:
  1. Switch to a GPU execution provider. CPU-only mode is significantly slower. Launch with --execution-provider cuda (NVIDIA), --execution-provider coreml (Apple), or --execution-provider directml (Windows AMD/Intel).
  2. Reduce execution threads. Too many threads can cause contention. Try a lower value: 
    python run.py --execution-provider cuda --execution-threads 4
  3. Disable the face enhancer. GFPGAN post-processing adds substantial per-frame cost. Uncheck the face enhancer in the GUI, or omit face_enhancer from the --frame-processor argument in CLI mode.
  4. Limit max memory. If the process is paging due to insufficient RAM, cap its usage: 
    python run.py --max-memory 8
For GPU execution on NVIDIA, verify that onnxruntime-gpu==1.21.0 is installed and that CUDA Toolkit 12.8.0 plus cuDNN v8.9.7 are present — missing drivers cause silent fallback to CPU.
On macOS, pip install -r requirements.txt can leave gfpgan and basicsr in a broken state due to conflicting build metadata. If the face enhancer crashes or fails to load, reinstall both packages directly from their GitHub repositories.First, tear down and recreate your virtual environment:
deactivate
rm -rf venv
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
Then apply the fix:
pip install git+https://github.com/xinntao/BasicSR.git@master
pip uninstall gfpgan -y
pip install git+https://github.com/TencentARC/GFPGAN.git@master
Relaunch Deep-Live-Cam and enable the face enhancer to confirm it loads without error.
Having multiple Python versions installed via Homebrew can cause the wrong interpreter to be selected when creating virtual environments or running scripts. Check which versions are installed:
brew list | grep python
If you see versions other than 3.11 (such as 3.13), consider uninstalling them to eliminate ambiguity:
brew uninstall --ignore-dependencies python@3.13
brew cleanup
Always create the virtual environment and run Deep-Live-Cam with the explicit python3.11 command:
python3.11 -m venv venv
source venv/bin/activate
python3.11 run.py --execution-provider coreml
Deep-Live-Cam includes a built-in content filter powered by opennsfw2 that automatically blocks processing of nudity, graphic violence, and other sensitive material. This is intentional and cannot be disabled without modifying the source code.
Attempting to bypass the NSFW filter violates the project’s ethical use policy. Users are responsible for ensuring their use of the software aligns with ethical standards and legal requirements. See the ethics and legal guidelines page for details.
If legitimate content is being incorrectly flagged, check that your source or target image does not contain partial nudity, graphic imagery, or other material the model classifies as sensitive. Use a different source image or target file.

Build docs developers (and LLMs) love

Get started for freeTalk to us