How to use FaceFusion 3.9.0: setup, settings and fixes
How to use FaceFusion 3.9.0: setup, settings and fixes
To use FaceFusion, install it locally, add a source face photo and a target photo or video, select the person to replace, preview the result, and run the swap. Use reference selection when a video contains several people; start with face swapping alone before adding enhancement or larger output settings.
This guide covers FaceFusion 3.9.0, released September 3, 2026. Commands were checked against the tagged release and official documentation on September 10; this is a setup guide, not a hardware speed benchmark. If you want a browser workflow without managing Python or GPU drivers, try Magic Hour Face Swap.
What you need before installing FaceFusion
FaceFusion runs on your computer and opens a browser interface. A local browser interface does not mean your job runs in a cloud service. Installation and model downloads need network access; processing requirements depend on your selected models, video length, resolution and hardware.
| Route | What it involves | Choose it when |
|---|---|---|
| Official Windows or macOS installer | A paid installer from the FaceFusion project; the shop lists Windows at $20 and macOS at $30 | You want the project's packaged installation route |
| Manual source installation | Git, Conda, FFmpeg and the runtime appropriate to your machine | You can maintain a Python environment and diagnose dependencies |
| Browser face-swap service | Upload inputs to a hosted tool; review its limits and data policies | You want an occasional swap without local installation |
Use the official FaceFusion shop for packaged installers. Third-party tutorials and launchers can target older releases. Paying for an installer also does not override the licenses of the models you choose.
For manual setup, follow the platform prerequisites for Windows, macOS or Linux. Confirm that Git, Conda and FFmpeg are available before proceeding. An NVIDIA runtime is not an interchangeable choice for Apple or AMD hardware.
Test a face swap on your own video
Upload a short clip and a clear replacement portrait to Magic Hour, then inspect identity tracking through motion before processing a longer video.
How to install FaceFusion 3.9.0 manually
The following example uses a fresh environment and folder named facefusion-390 so it can sit beside an existing installation. Run commands one at a time. If either name already exists, choose another unused name consistently; do not overwrite a working setup to follow a tutorial.
1. Initialize Conda and create an environment
If Conda has not been initialized for your terminal, run:
conda init --all
Reopen the terminal if Conda requests it, then create and activate the environment:
conda create --name facefusion-390 python=3.12 pip=25.0
conda activate facefusion-390
These Python and pip versions follow the current installation instructions. Keeping FaceFusion in its own environment avoids changing the runtime of an unrelated project.
2. Download the release covered here
git clone --branch 3.9.0 --depth 1 https://github.com/facefusion/facefusion facefusion-390
cd facefusion-390
This selects the 3.9.0 release, rather than whatever happens to be on the development branch later. A detached-HEAD notice is normal when checking out a release tag.
3. Install one appropriate runtime
FaceFusion 3.9.0 takes the runtime as a positional argument. The old tutorial's --onnxruntime installation syntax does not match this release's installer source.
| Your intended execution route | Installation command | Before using it |
|---|---|---|
| CPU | python install.py default |
Expect workload-dependent processing time |
python install.py default |
Confirm CoreML is available on your supported Mac | |
python install.py cuda@12 |
Complete the matching accelerator and driver setup | |
python install.py directml |
Check the Windows accelerator requirements for your GPU | |
python install.py migraphx |
Follow the supported Linux accelerator configuration | |
python install.py openvino |
Check platform and hardware compatibility |
Do not run every row. Follow the relevant Windows accelerator or Linux accelerator instructions, then install the runtime for that route. The install command and the provider selected when processing are separate settings.
4. Reload the environment and launch
conda deactivate
conda activate facefusion-390
From the facefusion-390 project directory, run:
python facefusion.py run --open-browser
Keep the terminal open while using the interface. On first use, required model downloads can add time before a preview or job is ready. Read the terminal message before treating a download or dependency error as a failed face swap.
Make your first photo or video face swap
- Choose a source photo. This supplies the replacement identity. Start with a clear, well-lit face that is large enough to inspect, without heavy filters or an obstruction across the eyes or mouth.
- Add a target. This is the photo or video receiving the replacement face. For an initial video check, choose a short, representative section instead of rendering a long clip immediately.
- Enable the face swapper processor. Leave additional enhancement and editing processors off while checking whether the intended face is detected and selected.
- Select the correct person. Use one for a simple single-person target, reference to follow a selected identity, or many when you intentionally want all detected faces changed.
- Inspect the preview. In video, check a clear frontal frame, a head turn and an obstructed frame if those occur. One clean frame cannot establish that a whole clip is ready.
- Choose an output location and start processing. Open the exported file afterward. Check face selection, transitions, sound and playback before sharing it.
The source and target have different jobs: a sharper source can help supply a clearer identity, but it cannot guarantee recovery of a face that is tiny, hidden or motion-blurred in the target. Choose better inputs before increasing every setting.
Which FaceFusion settings should you change first?
Work on one visible problem at a time. The 3.9.0 face-swapper source defaults to hyperswap_1a_256; older tutorials often name INSwapper as the default. New model availability is not evidence that one model wins on every face or clip.
| Setting | What it changes | Practical starting point |
|---|---|---|
| Face selector mode | Which detected faces receive the swap | One for a single person; reference for a chosen person in a group |
| Face selector order | Which face is first in one mode | Choose the order that selects your intended person; do not assume left-to-right |
| Reference frame and reference face | The identity used for matching | Pick a frame where that person is clearly visible |
| Reference face distance | How permissive identity matching is | Adjust gradually and inspect other people for unintended swaps |
| Face mask type | Which parts of the detected face are blended | Inspect box masking first; consider occlusion or region controls for a specific issue |
| Face enhancement | Restoration applied to the face | Add only after selection and blending are acceptable; inspect for altered texture or identity |
| Pixel boost and output scale | Processing or export resolution settings | Increase only when the smaller result and memory use are acceptable |
One does not mean “track this person throughout the video.” It selects a face using the configured ordering and filters. In a group scene, the first face can change as people move. Reference mode is the more relevant control when you want a particular identity. See the face selector documentation.
Masking also has distinct purposes. Occlusion masking can help retain an object crossing the face; region controls limit which facial regions participate in the blend. Neither is a guaranteed repair for every hand, pair of glasses or extreme angle. Use the preview to judge the actual affected frames. The mask documentation lists supported controls.
Troubleshooting: fix the symptom you actually see
| Symptom | Check first | Next useful action |
|---|---|---|
| Conda activation or Python import fails | Correct environment and project directory | Reactivate the intended environment; read the first relevant terminal error before reinstalling |
| CUDA or another GPU provider is unavailable | Installed runtime, hardware support and driver dependencies | Follow the platform accelerator guide; selecting a provider does not install it |
| Preview has no swap | Source face, target detection and enabled processors | Try a clearer target frame and confirm face_swapper is enabled |
| The wrong person changes | Selector mode, ordering and reference identity | Use a clear reference frame and inspect all people after adjusting matching |
| A turned face stops matching | Visibility, blur and the reference identity | Compare nearby frames and a better reference; image-rotation detection angles do not reconstruct a hidden side of a face |
| Glasses or a hand become distorted | Mask coverage in the affected frames | Compare occlusion or region settings at that moment, rather than judging only an unobstructed frame |
| Skin becomes unnaturally smooth | Enhancement and source image | Reduce or disable enhancement and compare against the unenhanced swap |
| Video memory runs out | Additional processors, pixel boost and workload | Reduce the workload and use a conservative memory strategy before increasing threads |
| Export lacks audio or has playback trouble | Source audio, output volume, encoder and final file | Check the output settings and terminal log; play the completed file in the intended destination |
There is no defensible universal “best thread count” or completion time. CPU/GPU, runtime, models, frame count and processing settings all matter. The memory controls trade processing speed against memory use; more threads are not automatically faster.
For a broadly compatible MP4 starting point, FaceFusion exposes H.264 through libx264 and AAC audio. AAC is the current default audio encoder, not FLAC. Review output creation settings when changing frame rate, scale, compression or sound. An output-quality slider is an encoding control, not proof of more accurate face identity.
Run a swap from the command line
After installation, this single-person example uses files in the current project directory and writes a named MP4 file:
python facefusion.py headless-run --source-paths "source.jpg" --target-path "target.mp4" --output-path "output.mp4" --processors face_swapper --face-selector-mode one
Replace those paths with your files. Quote paths containing spaces. This example does not select a GPU provider or change the model; your available provider and configuration still matter. For a target with several people, configure reference selection instead of assuming one mode will consistently follow the right person.
To see the arguments accepted by your installed version:
python facefusion.py headless-run --help
Upgrading from FaceFusion 3.6.0
This page previously covered 3.6.0. If you followed that version, keep its environment until the new installation opens and exports your representative clip correctly. Create a separate environment for 3.9.0, use the current positional runtime command, and review settings instead of assuming old presets have the same effect.
The 3.9.0 release adds AlphaFace to the face swapper and HRFFA to the face landmarker. That describes new options, not a benchmark result. Check each model's license and your actual output before switching a production workflow.
Is FaceFusion free, and can you use it commercially?
The source is available without buying the packaged installer. That does not make every supported model unrestricted for commercial use. FaceFusion's license inventory lists OpenRAIL-AS for the application and separate terms for its assets. AlphaFace, INSwapper and ArcFace are listed as non-commercial; HyperSwap uses ResearchRAIL.
Check the complete pipeline you intend to use, including recognition and restoration assets, rather than checking only the visible face-swapper model. You also need permission to use the person's likeness and the source footage. Do not present a face swap as evidence of something a real person said or did.
When a browser tool is the better fit
Choose FaceFusion when local processing, model selection and detailed masking justify maintaining the setup. Choose a hosted tool when completing a photo or video swap matters more than controlling its local runtime.