FaceFusion: a Python face swap and lip sync platform you run yourself

The problem FaceFusion solves, and who it is for

FaceFusion is a self-hosted tool for manipulating faces in images and video. The repository topics name the concrete jobs: face-swap and faceswap, lip-sync and lipsync, deep-fake. So the audience is people who need to replace one face with another in a clip, or make a mouth move to match an audio track, and who are willing to run that work on their own machine rather than upload footage to a service.

The README describes the project as an "Industry leading face manipulation platform", which is marketing language rather than a specification. What is verifiable is the shape of the thing: a Python program with a command line entry point, a Gradio dependency for a browser interface, and ONNX Runtime for inference. The requirements.txt pins gradio, numpy, onnx, onnxruntime, opencv-python-headless, scipy and tqdm, so the intended deployment is a local Python environment with enough compute to run ONNX models.

Who is it for, then? Not beginners. The README says the installation "needs technical skills and is not recommended for beginners", and points people who are not comfortable in a terminal at the Windows and macOS installers. That sentence is the clearest signal in the whole document about the intended user: someone who can create a Python environment, run an install script, and debug a model download.

How FaceFusion is put together: one entry point, many jobs

The architecture visible from the repository root is a single script plus a package. facefusion.py is the entry point, facefusion/ is the package, facefusion.ini holds configuration, and install.py handles setup. requirements.txt pins the runtime dependencies. tests/ sits alongside them, and the README carries build and coverage badges, so there is a test suite and CI.

The command line is organized around subcommands rather than flags. The README lists run, headless-run and batch-run for execution, force-download to pull models, benchmark to measure the program, and then a job system: job-list, job-create, job-submit, job-submit-all, job-delete, job-delete-all, job-add-step, job-remix-step, job-insert-step, job-remove-step, job-run, job-run-all, job-retry and job-retry-all.

That job vocabulary is the interesting part. Jobs have statuses (drafted, queued, failed, completed), and a job is built from steps that can be added, inserted, removed or remixed. This is a pipeline model: you compose a sequence of processing steps, submit it, and run it. The remix and insert commands suggest a job can be derived from a previous one rather than written from scratch. For anyone processing many clips, the job system is the feature that separates FaceFusion from a one-shot script.

One structural detail is worth flagging. The README documents the commands but not the options attached to them. Running the help output is the only way to learn what a given step accepts, and the README does not reproduce that output beyond -h, --help and -v, --version.

Installing FaceFusion and running a first face swap

The README does not inline the install commands. It links to https://docs.facefusion.io/installation and says the process needs technical skills. The repository, however, contains install.py at the root, which is the script the documentation points at. A typical sequence starts by creating an environment and installing the pinned requirements, then running the install script, then invoking the program.

The first block creates an isolated Python environment and installs the pinned dependencies from requirements.txt. You should see pip resolve gradio, onnxruntime, opencv-python-headless and the rest at the exact versions listed.

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

On Windows the activation line differs (venv\Scripts\activate). The README does not spell either out; it defers to the documentation site.

Next, the install script. This is the step the README warns about, and it is where model downloads and platform-specific setup happen.

python install.py

After that, the README gives the exact invocation for the program itself:

python facefusion.py [commands] [options]

To actually process something, you use the run command. The README does not document the per-command options, so check the help output before assuming a flag exists:

python facefusion.py run --help

For unattended work, headless-run and batch-run are the alternatives to the interactive path. The Gradio dependency in requirements.txt is what backs the browser interface; the README does not describe which command launches it, so treat that as something to confirm against the documentation rather than guess. If model files are missing, force-download is the documented way to fetch them:

python facefusion.py force-download

That is the honest extent of what the README supports as a tutorial. Everything past the entry point lives on docs.facefusion.io.

Where FaceFusion gets in the way

The first limitation is stated by the project itself: installation needs technical skills and is not recommended for beginners. That is not modesty, it is a support boundary. If you cannot debug a Python environment, an ONNX Runtime install, or a failed model download, the terminal route will cost you more time than it saves. The Windows and macOS installers exist precisely because of this, and choosing them means accepting less control over the environment.

The second limitation is the licence. The README's badge says OpenRAIL-AS, and the repository's licence field is NOASSERTION, meaning GitHub could not classify it automatically. OpenRAIL licences carry use restrictions, so the practical question is not "is the source readable" but "what am I allowed to do with the output and with the model weights". The README does not discuss this at all, and the licence implications are not something to infer from a badge.

The third is documentation coverage. The command list in the README is long and the explanation is short. There is no worked example of a job pipeline, no description of what a step contains, and no statement of which models are downloaded or how large they are. For a tool whose whole value is a processing pipeline, that is a real gap.

Fourth, the dependency pins are aggressive. numpy 2.4.6, onnxruntime 1.29.0, opencv-python-headless 5.0.0.93 and gradio 5.50.0 are exact versions, not ranges. That is good for reproducibility and bad for coexistence: dropping FaceFusion into an existing environment that already pins different versions of numpy or gradio will conflict.

Finally, consider what this tool is not. It is not a hosted API, and the README documents no server mode or authentication. If your requirement is to call face swap from another service over HTTP, nothing in the README describes that path.

FaceFusion compared with InsightFace and hosted face swap APIs

The closest thing to an alternative in the same space is InsightFace, the model and library ecosystem that many face swap projects build on. The difference is scope. InsightFace is a face analysis and recognition library: detection, alignment, embeddings, model zoo. It gives you components. FaceFusion is an application: it gives you an entry point, a Gradio interface, a batch mode and a job queue, plus the model downloads wired in. If you want to build your own pipeline and control every stage, the library is the better fit. If you want to process a folder of videos without writing the pipeline yourself, FaceFusion is the shorter path.

The other alternative is a hosted face swap service or a cloud notebook. Those remove the installation entirely, which is exactly the pain point the README warns about. The trade-off is the opposite of self-hosting: your footage leaves your machine, you depend on someone else's quota and pricing, and you cannot run offline. FaceFusion's batch-run and job-run-all commands are the argument for self-hosting, because they let you queue work locally without an upload step.

The honest comparison is about where the complexity lives. FaceFusion moves it into your environment. A hosted service moves it into someone else's, and charges for the privilege.

Maintenance, releases and what an upgrade costs

The project is not archived, and the last push was on 2026-09-10, a week before this writing. Releases are frequent: 3.9.0 on 2026-09-03, 3.8.3 on 2026-09-01, 3.8.2 on 2026-08-10. Three releases in roughly a month is a fast cadence, and it cuts both ways. You get fixes quickly. You also get churn, and the pinned requirements mean an upgrade can move numpy, onnxruntime and gradio at the same time.

The upgrade cost is therefore not just pulling new code. Because requirements.txt uses exact pins, upgrading FaceFusion can force a rebuild of the whole environment, and any other package in that environment that shares a dependency has to be re-checked. The install.py script is the documented setup path, so a clean environment per version is the lowest-risk approach; the README says nothing about in-place upgrades or migration between versions.

On licence: the badge reads OpenRAIL-AS and the repository licence field reads NOASSERTION. Those two facts together mean you should read LICENSE.md yourself before any commercial or public-facing use, and check the terms attached to the model weights that install.py downloads, which the README does not enumerate. This is not legal advice; it is a pointer to the two files that matter.

Editorial conclusion

FaceFusion suits engineers and technically comfortable users who want a self-hosted face swap and lip sync pipeline they can drive from a terminal, batch, or job queue. It is the wrong tool if you will not touch a command line (use the Windows or macOS installer instead, or a hosted service), and it is the wrong tool if you need a permissive licence, since the licence badge points to OpenRAIL-AS with its use restrictions. Before adopting it, verify the exact licence text in LICENSE.md, check that install.py resolves on your platform and Python version, and confirm the models you need are downloadable in your network.

Frequently asked questions

Official sources

1. facefusion/facefusion on GitHub
2. Issues
3. Project website
4. README
5. Releases