FaceFusion 3.9.0 guide: official install, settings & fixes

The official FaceFusion project is the local face-manipulation software at facefusion.io and github.com/facefusion/facefusion. Similarly named cloud face-swap sites are separate products. This distinction matters before you download software, buy an installer, follow setup instructions or evaluate privacy claims.

This guide covers FaceFusion 3.9.0, released September 3, 2026. Commands were checked against the tagged release and official documentation on September 13; 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.

If you are moving from Roop, read our current Roop AI status guide first. It separates the archived official project from unrelated sites and compares FaceFusion with supported browser and extension workflows.

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.

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.

Before installing locally, compare the verified free entry points in our best free AI face swap tools guide.

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.

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

1. 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.
2. 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.
3. Enable the face swapper processor. Leave additional enhancement and editing processors off while checking whether the intended face is detected and selected.
4. 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.
5. 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.
6. 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.

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

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

Headless processing, batch patterns and queued jobs are different workflows. Headless-run handles a specified input/output job. Batch-run accepts source, target and output patterns. The job manager creates and submits jobs, while job-run and job-run-all execute submitted jobs. Use the CLI command reference and job runner documentation for the workflow you need.

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.

For a quick comparison, use Magic Hour's photo face swap or video face swap with the same permitted inputs. Check the current preview, free limits and output requirements before upgrading. For several people, start with multiple face swap. Our face-swap app comparison separates photo, video, credit and licensing differences across the main alternatives.