Open-source project
facefusion/facefusion avatar
facefusion/facefusion

FaceFusion: a single-script face manipulation tool whose setup lives outside the repository

Industry leading face manipulation platform

30,653 stars5,020 forksPythonNOASSERTION

At a glance

What is it?
FaceFusion is a Python face manipulation program driven from facefusion.py with five commands. The code ships with exact dependency pins and frequent point releases, but installation, licensing terms and most options have to be read from places other than the README.
Who is it for?
FaceFusion suits users who are comfortable in a terminal and a dedicated Python environment, or Windows and macOS users willing to use the project's installers. It is a poor fit for someone who wants to understand every option from the repository alone, since installation steps and command details sit on docs.facefusion.io.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • facefusion/facefusion30,653 ★ · +761
Star history
Repository2026-09-132026-11-13
facefusion/facefusion29.9k30.7k

761 Stars in the last 61 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Everything starts from one entry script, facefusion.py

FaceFusion presents itself as an industry leading face manipulation platform, written in Python. Whatever route you take to install it, the program is driven from a single file at the repository root, `facefusion.py`, which takes a command and then options:

code
python facefusion.py [commands] [options]

The repository layout is compact. Next to the entry script sit `facefusion/`, the package directory, `install.py`, `requirements.txt`, `facefusion.ini` and `facefusion.ico`. The ini file's name marks it as the program's configuration file, so it is the first file to open if you want to know which defaults the program starts from. The `tests/` directory, a `mypy.ini`, a `.flake8` file and a `.coveragerc` show that the code is type checked, linted and measured for coverage, and the README carries badges for a CI workflow and for Coveralls coverage reporting.

Five commands, and benchmark has no help text

The help output printed in the README shows two global options, `-h, --help` to show the help message and exit and `-v, --version` to print the version number and exit, followed by five commands:

code
options:
  -h, --help                                      show this help message and exit
  -v, --version                                   show program's version number and exit

commands:
    run                                           run the program
    headless-run                                  run the program in headless mode
    batch-run                                     run the program in batch mode
    force-download                                force automate downloads and exit
    benchmark

The split between `run`, `headless-run` and `batch-run` is the core of how you choose to operate it: interactively, without an interface, or across a batch of jobs. The README stops at these one-line descriptions, so the options each command accepts are not visible from the repository front page. Running `-h` against a specific command or reading docs.facefusion.io is the way to find them.

The `benchmark` command is listed with no description at all. Nothing in the help text says what it measures or what it prints, so treat it as undocumented until you have read its entry on the documentation site or run it yourself.

Installation is handed off to an external guide

The README contains no install command. Its Installation section opens with a warning: the installation needs technical skills and is not recommended for beginners. The manual steps live at https://docs.facefusion.io/installation, not in the repository.

For people who are not comfortable using a terminal, the project points to two packaged routes instead: a Windows Installer at http://windows-installer.facefusion.io and a macOS Installer at http://macos-installer.facefusion.io. No installer is listed for Linux, so Linux users are left with the manual route described on the documentation site.

The consequence is that cloning the repository does not tell you what to run next. `install.py` and `requirements.txt` are both present at the root, but the order and flags for using them are on the external page. If that page is unavailable, or you are reviewing the project offline, the repository alone does not get you to a working installation.

Exact pins in requirements.txt rule out a shared environment

Every dependency in `requirements.txt` is pinned to an exact version with `==`:

code
gradio-rangeslider==0.0.8
gradio==5.50.0
numpy==2.5.4
onnx==1.23.2
onnxruntime==1.31.0
opencv-python-headless==5.0.0.93
tqdm==4.70.1
scipy==1.18.1

The list shows the shape of the program. Models are handled through `onnx` and `onnxruntime`, image and video processing goes through the headless build of OpenCV, `numpy` and `scipy` handle the numerical work, `tqdm` provides progress bars, and `gradio` with `gradio-rangeslider` provides the interface components.

The cost of exact pins is that FaceFusion will fight with any other project installed in the same Python environment that needs a different numpy, OpenCV or onnxruntime. Give it a dedicated virtual environment. The pins also mean you do not get dependency fixes until a FaceFusion release raises them.

force-download separates fetching from running

One command in the list exists purely for logistics: `force-download`, described as forcing automated downloads and then exiting. The wording tells you two things. First, FaceFusion automates downloads of the files it needs rather than shipping them in the repository. Second, you can trigger those downloads on their own, without starting a run.

That matters when the machine doing the work is not the machine with good connectivity, or when you want setup and processing to fail independently. Running `force-download` once after installation lets you see download problems immediately, instead of having them interrupt the first `run`, `headless-run` or `batch-run`. The help text does not say which files are fetched or where they are stored, so check the documentation site if disk space or a restricted network is a concern.

GitHub cannot name the license

GitHub's metadata for the repository reports the license as NOASSERTION, meaning its detection did not match the license file to a standard identifier. The terms themselves are in `LICENSE.md` at the repository root.

This has a direct consequence for anyone planning more than personal use. A public repository on GitHub is not the same as a permissive license, and automated dependency or compliance scanners that rely on GitHub's license detection will have nothing to report for FaceFusion. Read `LICENSE.md` yourself before bundling the code, redistributing it, or using it in a commercial setting, and do not infer the terms from the fact that the source is downloadable. The same applies to the Windows and macOS installers: their terms are not stated on the repository front page.

Three point releases in eight weeks, titled only by number

The project ships often. Release 3.9.0 appeared on September 3, 2026, 3.9.1 on September 30, 2026, and 3.9.2 on October 26, 2026. The repository is not archived and its last push was on October 4, 2026.

The release titles are just the version numbers, so the releases list on its own does not tell you what moved between 3.9.0 and 3.9.2. Tutorials and forum threads written for earlier 3.x versions describe a program that has since gone through several releases, and the commands or options they show may not match what your installed copy accepts. Before following any walkthrough, run `python facefusion.py -v` to confirm your version, compare it with the version the guide was written for, and check the documentation site for that release.

Editorial conclusion

FaceFusion suits users who are comfortable in a terminal and a dedicated Python environment, or Windows and macOS users willing to use the project's installers. It is a poor fit for someone who wants to understand every option from the repository alone, since installation steps and command details sit on docs.facefusion.io. Before using it for anything beyond personal experiments, read LICENSE.md, because GitHub does not identify a standard license for the project, and check which 3.9.x release you are on.

Frequently asked questions

How do I install FaceFusion?

FaceFusion's README links to a manual installation guide at https://docs.facefusion.io/installation and warns that it needs technical skills and is not recommended for beginners. Users who are not comfortable with a terminal can use the Windows or macOS installer instead.

How do I install FaceFusion on Windows?

The project offers a Windows Installer at http://windows-installer.facefusion.io for people who do not want to use a terminal. The manual route is described at https://docs.facefusion.io/installation.

How do I use FaceFusion on a Mac?

FaceFusion has a macOS Installer at http://macos-installer.facefusion.io. Once installed, the program is driven by python facefusion.py with a command such as run, headless-run or batch-run.

How do I use FaceFusion locally?

After installing, run python facefusion.py followed by a command: run for the normal mode, headless-run for headless mode, or batch-run for batch mode. The documentation at https://docs.facefusion.io covers the options in detail.

Is FaceFusion free to use?

The FaceFusion source code is public on GitHub, but GitHub does not identify a standard license for it. The terms are in LICENSE.md in the repository, which you should read before relying on it.

Official sources

  1. facefusion/facefusion on GitHub
  2. Issues
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/facefusion-facefusion.svg)](https://hysenlabs.com/projects/facefusion-facefusion)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/facefusion-facefusion.svg)](https://hysenlabs.com/projects/facefusion-facefusion)

Was this useful?