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.

Version update — October 2, 2026: the latest official patch is FaceFusion 3.9.1, released September 30. The official changelog records ONNX Runtime updates and a CoreML content-analyser performance fix. The commands below deliberately pin 3.9.0 for reproducibility; they do not install the latest patch. For a new installation, check the current official instructions and release before choosing a version. We have not benchmarked 3.9.1.

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

Source: official FaceFusion repository

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

CPU-only launch: If you installed the default CPU runtime, select the CPU provider explicitly. Processing time depends on your CPU, selected models and video settings.

python facefusion.py run --execution-providers cpu --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.

Keep the intended person selected in a group video

Reference mode compares detected target faces with a selected face from the target, not with a fixed screen location. The source photo still supplies the replacement identity. This distinction matters when two people exchange positions: selecting the leftmost face on every frame is a different task from matching the same person. The following example is illustrative, not a generated-output test.

Suppose a consented interview clip contains Alex and Jordan, and only Alex should receive the source identity. Alex is clearly visible on the left at reference frame 120, then walks past Jordan and appears on the right. The acceptance rule is Alex changed, Jordan unchanged, including the crossing and return from any obstruction. Frame 120 is an example value; choose a frame that exists in your actual clip and shows the intended face clearly.

In the 3.9.0 interface, choose reference mode, move the preview frame slider to that clear frame, and inspect the reference-face gallery. Set the selector order before selecting the face; left-right makes the leftmost detected face first. Check any active demographic or age filters because ordering and filtering determine the reference gallery. Click Alex’s face in that gallery. The selection records both the current preview frame and the selected face position. Changing the target clears those reference values, so select again after loading another file.

For a headless equivalent, this command explicitly uses reference mode, left-right order, the first reference face and the documented 0.3 distance default. It assumes Alex is the first detected face after the configured filters at frame 120. Run it from the installed FaceFusion project directory with your own paths:

python facefusion.py headless-run --source-paths "source.jpg" --target-path "target-group.mp4" --output-path "output-group.mp4" --processors face_swapper --face-selector-mode reference --face-selector-order left-right --reference-face-position 0 --reference-frame-number 120 --reference-face-distance 0.3

Position 0 means the first face in the ordered, filtered reference list; position 1 means the second. It is not a permanent person ID. Do not guess an index from the number of people in the scene: in 3.9.0, an index beyond the detected list is clamped to the last face. Confirm the gallery, order and filters first. The command does not reset other configuration, choose an execution provider or override the swapper model.

Distance controls matching tolerance, not face quality. The pinned 3.9.0 implementation accepts a target face when its normalized distance is below the configured threshold. Raising the value admits more matches; lowering it is stricter and can exclude the intended person. Reference mode can therefore match more than one face. There is no threshold that guarantees Alex will always match while Jordan never does. Keep the reference frame and other controls fixed while making a small distance change, then inspect both people again.

Separate two failure cases before changing settings. If Alex is already wrong in the clear reference frame, recheck the selected gallery face, frame, ordering and filters. If the clear frame is correct but Alex is missed during a turn, compare that original frame with its preview; first check whether a face is detected and whether the selected reference remains appropriate. Increasing matching tolerance cannot restore a face that was not detected. Recheck Jordan whenever you relax the distance. If Jordan starts changing, reject that setting even if Alex looks better.

Approve only after the exported file passes both positive and negative checks: Alex has the intended replacement across visible frames, Jordan retains the original identity, and the crossing, head turn and reappearance have no unintended swaps. Then inspect blending and ordinary playback separately. A correct selection does not establish a clean jawline, intact obstruction or usable audio. If one reference does not give acceptable coverage, choose a clearer reference or revise the affected shot before processing the full project.

These details were checked on October 5, 2026 against the official selector arguments, the 3.9.0 selection implementation, the reference gallery implementation and face-position handling. Keep this recipe tied to the installed version when upgrading.

Troubleshooting: fix the symptom you actually see

Check the documented CPU execution provider, browser launch option, analysis-halt FAQ and exit-code meanings against the actual terminal message. These are documented controls and error definitions, not a measured speed comparison.

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.

Keep the original voice or add new dialogue

Face swapping and lip syncing are separate operations. In the FaceFusion 3.9.0 workflow documented here, Source can contain images and audio. Check that panel before exporting: a source audio file changes which soundtrack the final video uses.

The pinned video-export code uses source audio when supplied, restores target audio otherwise, and emits silence at volume zero. For the original-dialogue workflow, remove unintended audio from Source. For new dialogue, add the intended recording and enable lip_syncer.

If you see “choose an audio for the source!”, check the selected processors. The lip-sync source check requires source audio; the target video’s embedded soundtrack does not satisfy it. Add the replacement recording if you want new dialogue, or disable lip_syncer for a face-only edit.

The official output-audio controls document volume and encoder settings. Listen to the final exported file with headphones, then check mouth movement around pauses and fast speech. An image preview cannot establish whether the final soundtrack is correct. These are documented code behaviors, not a generation test performed for this article.

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.

Batch one identity across clips without creating every pair

FaceFusion 3.9.0 combines every matched source with every matched target. It does not pair matching filenames. Two source portraits and three target clips create six combinations. To apply one identity across three clips, use one exact source path and a target pattern. This behavior comes from the 3.9.0 batch implementation.

From the FaceFusion project directory, replace these paths with your files. Choose an unused output-folder name and keep the originals. This example assumes one visible person per target; use the reference-selection guidance above for group footage.

mkdir outputs-first-test

python facefusion.py batch-run --source-pattern "sources/alex.jpg" --target-pattern "targets/*.mp4" --output-pattern "outputs-first-test/{target_name}-alex{target_extension}" --processors face_swapper --face-selector-mode one

Keep the patterns quoted. The pattern documentation describes the placeholders. In the pinned 3.9.0 implementation, target_extension includes its leading dot, so this example does not insert another dot. Review a first output before scaling the folder.

Retry the specific failed job

Fix the logged error first, then list failed jobs and retry the relevant ID rather than restarting every job:

python facefusion.py job-list failed

python facefusion.py job-retry YOUR_FAILED_JOB_ID

Replace YOUR_FAILED_JOB_ID with the actual ID from the list. Use the same environment and jobs directory as the original run. The job manager documents listing, and the job runner documents retrying one failed job. These commands illustrate the documented workflow; no new batch-output benchmark is claimed.

Batch retries can rerun completed clips. In FaceFusion 3.9.0, job-retry requeues every step in that job and runs its steps again. The batch command above puts its matched source–target combinations into one job. See the versioned retry implementation, all-step status reset, and batch job construction.

For illustration, if a three-clip batch fails on its third step, retrying that batch can process the first two steps again. Fix the logged cause before retrying and allow for the whole job’s workload. To test one revised target separately, use the single-file headless-run pattern above with that target and a new output filename. Keep the original inputs and any accepted exports.

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.

When to stop troubleshooting and use a browser workflow

Use FaceFusion when local control, configurable processors, and repeatable technical workflows justify installation. Use a browser tool when the job is occasional, setup time exceeds editing time, or you need a result before diagnosing Python, runtime, or GPU dependencies.

Set a time budget before debugging. Save the first relevant terminal error, confirm the installed release and selected runtime, then follow the matching official platform guide. If the same environment problem remains after one clean, documented attempt, compare a hosted workflow with the same consented source and target instead of repeatedly reinstalling unrelated packages.

For a fair output check, use one photo and one short video containing a profile turn or obstruction. Review identity, boundary quality, unintended changes, temporal consistency, export resolution, processing time, and data-policy fit. Local processing can offer more control; hosted processing can remove setup work. The better option depends on the whole job.