Deep-Live-Cam: Real-time single-image face swapping on any modern GPU

Deep-Live-Cam turns a single face photo into a real-time, one-click transformation engine for any video or live camera feed.

What is Deep-Live-Cam

Deep-Live-Cam is an open-source application for real-time face swapping and one-click deepfake video generation built around a simple GUI and a Python backend. Instead of training custom models, it uses pre-trained ONNX models to map a single source image onto target images, videos, or live webcam streams, making high-quality face replacement accessible on consumer hardware.

The tool is hosted on GitHub under the hacksider/Deep-Live-Cam repository and distributed via source code, mirrored builds, and community forks. Once installed, you launch python run.py, choose a source face image and a target image or video, click “Start,” and the program writes frames and the final output video to an output directory.

Core models, dependencies, and architecture

Face analysis and swapping models

Deep-Live-Cam uses InsightFace as its core face analysis library, providing face detection, landmarks, and recognition models such as the buffalo_l family downloaded into the user’s ~/.insightface/models directory. On top of InsightFace, it relies on the inswapper_128 family of ONNX models (including inswapper_128.onnx and inswapper_128_fp16.onnx) to perform the actual face swapping from a single source image to each detected target face.

For visual quality, Deep-Live-Cam integrates GFPGAN (GFPGANv1.4.pth) as a “face enhancement” or “face restoration” step, improving sharpness and texture in the swapped face. Additional components such as opennsfw2 are used for NSFW filtering, while FFmpeg handles video decoding/encoding and audio preservation.

Python, ONNX Runtime, and frame processors

The project targets Python 3.10–3.11 and uses a requirements file that includes PyTorch, ONNX Runtime variants, TensorFlow, InsightFace, GFPGAN, and related multimedia dependencies. Runtime inference is powered by ONNX Runtime with different “Inference Providers” (execution providers) such as CPUExecutionProvider, CUDA, CoreML, and DirectML, which you select via the --execution-provider flag.

On the processing side, the command-line interface exposes frame processors like face_swapper and face_enhancer, along with options such as --keep-fps, --keep-audio, --many-faces, --map-faces, --nsfw-filter, and several video encoding parameters (--video-encoder, --video-quality).

Setting up the environment

Installing Python, git, and FFmpeg

A reliable Deep-Live-Cam setup starts with a clean Python 3.10 installation, Git, and FFmpeg on your system. On Windows, a common pattern is to install Python 3.10, Git, and FFmpeg via Chocolatey, verifying each with python --version, git --version, and ffmpeg --version before continuing.

On macOS and Linux, you can install Python (3.10+), Git, and FFmpeg using your package manager or direct downloads, then confirm that python3, git, and ffmpeg are available in your shell PATH. FFmpeg is essential because Deep-Live-Cam uses it under the hood for video I/O, and missing or misconfigured FFmpeg often surfaces as “failed to initialize VideoCapture” or codec errors in logs.

Creating a virtual environment

Using a dedicated virtual environment (venv or Conda) isolates Deep-Live-Cam’s dependencies from your system Python and other projects. Many installation guides recommend creating a new environment (for example, via python -m venv venv or an Anaconda environment) before installing requirements, to avoid version conflicts in heavy packages like TensorFlow, ONNX Runtime, and numpy.

Inside your project directory, a typical sequence on any platform looks like:

python -m venv venv
# Windows: venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate
pip install --upgrade pip

This gives Deep-Live-Cam a clean, reproducible runtime where you can pin specific versions of onnxruntime-gpu, onnxruntime-directml, or onnxruntime-silicon as needed.

Cloning the repository and installing requirements

With prerequisites and a virtual environment in place, clone the repository and install dependencies:

git clone https://github.com/hacksider/Deep-Live-Cam.git
cd Deep-Live-Cam
pip install -r requirements.txt

The official and community readmes, as well as several blog posts, all follow this pattern and note that the first run will download ONNX models totaling roughly a few hundred megabytes. If model downloads fail or you prefer offline setup, you can manually download GFPGANv1.4.pth and inswapper_128_fp16.onnx from the project’s Hugging Face mirror and place them into the models/ directory.

Configuring inference providers for different hardware

Core CPU execution provider

If you do not specify an --execution-provider, Deep-Live-Cam typically defaults to using the CPU via CPUExecutionProvider in ONNX Runtime. You can explicitly force CPU mode with:

python run.py --execution-provider cpu

CPU mode is the most compatible configuration and works on almost any machine that satisfies the Python and FFmpeg requirements, though performance will be limited for high-resolution video or multi-face scenes.

NVIDIA GPUs with CUDA

For NVIDIA GPUs, Deep-Live-Cam relies on a CUDA-enabled onnxruntime-gpu build, in combination with a matching CUDA toolkit and cuDNN installation. Guides commonly recommend pinning onnxruntime-gpu to versions such as 1.16.3 or 1.21.0 to avoid numpy incompatibilities while providing stable GPU inference.

A typical NVIDIA setup looks like:

# Install or confirm CUDA and cuDNN
# Then inside your Deep-Live-Cam venv:
pip uninstall onnxruntime onnxruntime-gpu
pip install onnxruntime-gpu==1.21.0
python run.py --execution-provider cuda

When correctly configured, logs show Applied providers: ['CUDAExecutionProvider', 'CPUExecutionProvider'], and you should see higher FPS compared to CPU-only runs, limited mainly by your GPU model and VRAM.

AMD and Intel GPUs via DirectML

On Windows, Deep-Live-Cam can use DirectML (via onnxruntime-directml) to accelerate inference on AMD and many Intel GPUs. A common approach is:

pip uninstall onnxruntime onnxruntime-directml
pip install onnxruntime-directml==1.15.1
python run.py --execution-provider directml

DirectML provides a unified GPU backend for Windows users who do not have access to CUDA but still want faster-than-CPU performance for real-time streaming and higher resolutions.

Apple Silicon with CoreML

On Apple Silicon (M1/M2/M3), Deep-Live-Cam supports CoreML via an ONNX Runtime build tailored for macOS ARM. Typical setup steps include installing Python 3.10 via Homebrew, creating a venv, and then selecting the CoreML provider:

brew install [email protected]
python3.10 -m venv venv
source venv/bin/activate
pip uninstall onnxruntime onnxruntime-silicon
pip install onnxruntime-silicon==1.16.3
python run.py --execution-provider coreml

Under the hood, the model uses CoreMLExecutionProvider with a CPU fallback, providing efficient, battery-friendly acceleration on MacBook-class hardware.

Using the Deep-Live-Cam GUI

Selecting source image and target video

Once dependencies and models are in place, launching python run.py opens the Deep-Live-Cam GUI. In “Image/Video” mode, you:

1. Select a source image (the face you want to inject) via the GUI file picker.
2. Select a target image or video (the content where faces will be replaced).
3. Optionally set output directory and advanced options such as face enhancement, frame processors, and video encoder.
4. Click “Start” to begin processing.

As the program runs, it writes individual frames into a directory named after the target video and finally produces a rendered output file with the swapped face and (optionally) original audio and FPS preserved.

Running in live webcam mode

For real-time streaming, Deep-Live-Cam provides a “Live” mode that uses your webcam as the target stream. The typical workflow is:

1. Run python run.py to open the GUI.
2. Select a source face image as before.
3. Click the “Live” button to start webcam preview and face swapping.
4. Wait 10–30 seconds for the first preview frame while models are loaded and initialized.
5. Use OBS or another screen-capture/virtual-camera tool to route the Deep-Live-Cam window into video conferencing or streaming software.

You can change the source image during a session to instantly switch personas without restarting the program, making it useful for creative streaming setups and real-time demonstrations.

Optimization and troubleshooting

Managing model files and path issues

Many runtime errors are caused by missing or mismatched model files such as inswapper_128_fp16.onnx or corrupted ONNX downloads. If you see errors like “model_file … should exist” or ONNXRuntime INVALID_PROTOBUF when loading inswapper_128_fp16.onnx, confirm that:

• The models/ directory in your Deep-Live-Cam folder contains inswapper_128_fp16.onnx and GFPGANv1.4.pth downloaded from the official Hugging Face model repository.
• File paths match exactly what the code expects (watch for typos or extra extensions).
• If automatic download failed, manually re-download the ONNX model and overwrite the local copy.

Some users also resolve InsightFace model issues by manually placing detector/recognition models under ~/.insightface/models, following the paths printed in the logs (for example, buffalo_l/1k3d68.onnx and buffalo_l/w600k_r50.onnx).

Troubleshooting “insightface build error”

A frequent blocker on Windows is the “Failed building wheel for insightface” error when running pip install -r requirements.txt. Common mitigations include:

• Install build dependencies first: Visual C++ build tools and a consistent Python 3.10 environment reduce build-time failures for InsightFace and its compiled extensions.youtube+1
• Use a pre-built wheel: Some tutorials recommend downloading a compatible insightface wheel and installing it manually when local compilation fails.
• Pin compatible numpy and ONNX Runtime versions: Adjust onnxruntime-gpu (for example, 1.16.3) and set numpy==1.24.3 to satisfy both InsightFace and TensorFlow constraints, as documented in GitHub discussions.

If you continue to encounter errors, installing InsightFace into a fresh venv before running pip install -r requirements.txt can reveal whether the issue is with InsightFace itself or conflicting packages in the environment.

Improving quality and performance

Performance and quality tuning typically centers on:

• Selecting the right execution provider and threads: Use GPU providers (CUDA, DirectML, CoreML) with --execution-provider and adjust --execution-threads (e.g., 1 thread for GPU, more for CPU) to balance throughput and stability.
• Using face enhancement wisely: Enabling GFPGAN-based face enhancement can dramatically improve facial detail at the cost of some performance, but may be disabled on very low-end hardware or where FPS is critical.
• Controlling resolution and memory: Flags like --max-memory and options for live preview resizing (--live-resizable) help keep memory usage under control on GPUs with limited VRAM.

Testing at lower resolutions first, then gradually increasing resolution and enabling face enhancement, is a pragmatic path to reaching stable real-time streaming on your specific hardware.

Using deepfake technology responsibly

Deep-Live-Cam provides powerful capabilities for real-time face swapping and deepfake video generation, and that power comes with serious ethical and legal responsibilities. You should only use this tool with the explicit consent of everyone involved, respect platform terms of service, and avoid any use that could mislead, harass, or defame real individuals.

Many jurisdictions are actively updating laws around synthetic media, and misuse of deepfakes can result in real-world harm even when no law is technically broken. Treat Deep-Live-Cam as a creative or research tool, not a weapon—keep your experiments transparent, label synthetic content clearly, and avoid generating non-consensual or deceptive media.