Install Roop-Floyd v4.4.1 AI Face Swap [Guide]

End state first: a Gradio UI on http://127.0.0.1:7860, one source face, one target clip, Start – swap renders on your machine. No cloud upload. That’s Roop-Floyd v4.4.1 after a clean install.

Search results still say “Roop.” The tree people mean now is different. s0md3v/roop sits archived read-only; upstream work stopped. What still moves is Cognibuild/ROOP-FLOYD on Codeberg (v4.4.1 core, commit 518a3d1 tagged 2025-01-25, with later README/UI edits). This write-up follows the README’s GPU split and the pins that stop the usual post-pip crash – not the blurry one-path blogs.

What you need before the clone

Windows users hit the wall early: without Visual Studio Build Tools 2019+ (C++ workload), insightface often refuses to build a wheel. Fix that before you touch Git.

Baseline that still runs: Windows 10/11 64-bit, recent macOS, or Ubuntu-class Linux; i5/Ryzen 5-class CPU; 8 GB RAM (16 GB+ if you like breathing room); 10-20 GB disk; Python 3.10.x (code checks 3.9+, 3.10 dodges most insightface pain); Git; FFmpeg on PATH. NVIDIA CUDA with 4 GB+ VRAM is optional and strongly preferred. AMD on Windows can try DirectML; quality and speed vary.

First launch pulls roughly 2 GB of weights (inswapper, reswapper variants, GFPGAN, and friends) from Hugging Face paths wired in roop/core.py – as of the v4.4.1 tree. Budget bandwidth.

Official download source

git clone https://codeberg.org/Cognibuild/ROOP-FLOYD.git
cd ROOP-FLOYD

README also points at packaged helpers on roop.getgoingfast.pro and a Colab notebook in-repo. Skip random “one-click Roop” ZIPs. After the original archive, mirror quality got messy.

Install Roop-Floyd v4.4.1 step by step

Venv first. Windows CMD:

python -m venv venv
venvScriptsactivate

macOS/Linux: python3 -m venv venv && source venv/bin/activate. Prompt should show (venv).

Path A – NVIDIA 50-series (as of the current Codeberg README block)

1. pip install uv
2. uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
3. Install the packages that block lists (numpy, opencv-python-headless, onnx, insightface, albucore, psutil, onnxruntime / onnxruntime-gpu, tqdm, ftfy, regex, pyvirtualcam) or follow an updated requirements flow if you already maintain one.
4. UI stack pin that clears the common launch crash:

   pip install --force-reinstall pydantic==2.10.6
   pip install --upgrade gradio==5.13.0

Path B – 30/40-series NVIDIA (or AMD DirectML)

1. NVIDIA: conda install -c nvidia cudatoolkit=11.8 -y (docs assume Miniconda for that line).
2. AMD: pip install onnxruntime-directml
3. pip install -r requirements.txt – file aims at cu124 torch builds and pins such as numpy==1.26.4, insightface==0.7.3, onnxruntime-gpu (versions as of that file; re-read it after git pull).
4. Then tighten the stack:

   pip install --upgrade gradio --force
   pip install --upgrade fastapi pydantic
   pip install "numpy<2.0"

   If Gradio still dies on start, apply the same pydantic==2.10.6 + gradio==5.13.0 force pair from Path A.

Pro tip: cu128 torch on a 3070/4070 (or the reverse) is how you get CPU fallback or a hard CUDA error. The README keeps two blocks on purpose.

Assumed already on the machine: Python, Miniconda when you need the cudatoolkit line, Git, FFmpeg, VS Build Tools 2019+ on Windows.

Ever watch the last stretch of an AI install turn into pure weight-download anxiety while you re-read every pip line? That’s the next section. Normal.

First-time configuration and launch

python run.py

Keep the terminal open. Models land under a local models area on first run. When Gradio binds, browse to http://127.0.0.1:7860 if the browser does not pop itself. Provider logic prefers CUDA when it sees a device; settings can force CPU.

Smallest test that proves it works: one sharp front-facing face still + a short target image or clip. Pick faces in the UI, toggle an enhancer if you want cleaner frames, hit Start. No training set.

Verify the install works

Pass bar: terminal shows execution provider (cuda or cpu), Gradio serves with no traceback, source face shows in the gallery, a short target writes an output file, console stays quiet on missing modules and protobuf noise. UI up but preview throws ValueError: zero-size array or list-index errors? Jump to the pydantic/gradio pair in the errors list – that combo keeps showing up on v4.4.1 threads.

Optional: ffmpeg -version before a long video.

What if torch “works” yet every frame still smells like CPU timing – and you only find out after a 10-minute clip? Wrong wheel generation does that. Check the provider string before you blame the models.

Common install errors and fixes

• Gradio / pydantic blow-up (IndexError, list index, launch crash):pip install --force-reinstall pydantic==2.10.6 then pip install --upgrade gradio==5.13.0. Codeberg issues and install write-ups treat this pair as the reliable fix for current Floyd.
• Antivirus blocks launch (WinError / virus on frpc_windows_amd64): Gradio’s share helper trips Defender (same false-positive pattern called out in Gradio’s tracker, including issue #7296). Pause real-time scan or exclude the Gradio package path, launch once, turn protection back on.
• ffmpeg is not installed: Get a build from ffmpeg.org, put bin on PATH, reopen the terminal. Stills may limp; video will not.
• insightface build / wheel failure on Windows: VS Build Tools C++ workload, or a matching prebuilt insightface-0.7.3-cp310-... wheel. Stay on Python 3.10 when you can.
• GPU ignored / CUDA errors: Torch wheel must match card generation; driver and toolkit have to agree. Force CPU in settings only as a fallback.
• numpy 2.x fights: Keep numpy<2 / 1.26.4 the way requirements intend.

People often run FaceFusion-style tools or Rope on the same NVIDIA box – different UI, same demand for clean CUDA and FFmpeg.

Upgrade and uninstall

Upgrade is boring on purpose. Activate the same venv, git pull (or re-clone if you heavily patched files), re-apply the dependency pins for your GPU path, python run.py. No migrator. Models already on disk usually stay.

Cleanup: deactivate, delete the ROOP-FLOYD folder and its venv. Global insightface/onnx leftovers only if nothing else needs them. Wipe project models plus any user-level insightface cache to reclaim the ~2 GB. Stock install registers no Windows service.

FAQ

Is the original Roop still the right download?

No. Use Roop-Floyd on Codeberg. The GitHub original is archived.

Why does my 4070 fail after I followed a “50-series” blog post?

You mixed blocks. A 4070 needs the 30/40 path (toolkit/requirements style), not the 50-series uv + cu128 torch index. After the right block, if the UI still crashes on launch, apply the pydantic 2.10.6 / gradio 5.13.0 force reinstall once – don’t keep shopping random CUDA indexes.

Can I run AI face swap without an NVIDIA card?

Yes. CPU mode is fine for stills and short clips; long video crawls. Windows AMD: try onnxruntime-directml. macOS is workable with the repo’s non-NVIDIA dependency routes, but expect slower frames either way. FFmpeg still matters for video. Separate from hardware: get consent before using someone’s face, and label synthetic media when you publish. The project disclaimer is doing real work, not filler.

Clone Codeberg. Match the GPU block to the card you own. Pin pydantic. Run python run.py. First clean output file beats any checklist.