FaceFusion: what the CLI surface tells you before you install it

The problem FaceFusion targets and the users it assumes

FaceFusion is a face manipulation platform written in Python. The repository topics list the specific operations it covers: face swap, deepfake generation, and lip sync. That is a narrower scope than a general video editing tool. If your task is replacing one face with another across a clip, or driving a mouth from an audio track, those are the two jobs the project names for itself. The README's own description is a single line, "Industry leading face manipulation platform," which is a claim rather than a specification, so the topics list is the more useful signal about what the software actually does. The intended user is someone comfortable in a terminal. The README states plainly that installation "needs technical skills and is not recommended for beginners," and then points beginners at separate Windows and macOS installers hosted at windows-installer.facefusion.io and macos-installer.facefusion.io. That split tells you the project expects two audiences: people who will run python facefusion.py directly, and people who want a packaged binary. The second group is served by a download that is not part of this repository, which matters if you are evaluating the codebase itself rather than the product.

How the command surface is organised

Everything the README documents runs through one entry point: python facefusion.py [commands] [options]. The options block is small, only -h and -v. All the substance sits in the commands. There are three ways to execute work. run is the interactive path. headless-run is the same work without a user interface, which is what you would call from a scheduler or a container. batch-run processes a batch rather than a single invocation. Alongside those, the project exposes a persistent job queue. job-create makes a drafted job, job-submit moves a drafted job to queued, and job-run executes a queued job. There are bulk variants: job-submit-all, job-run-all, job-retry-all, job-delete-all. A job is not a single operation, it is a sequence of steps, and the CLI reflects that with job-add-step, job-insert-step, job-remove-step, and job-remix-step, which the README describes as remixing "a previous step from a drafted job." So the data model is a job containing ordered steps, with a status lifecycle of drafted, queued, failed, completed, which is the set job-list filters on and the set job-delete-all clears. That is a more structured design than a one-shot script, and it is the part of the project the README actually specifies rather than asserts.

Getting it running from the documented commands

The README gives no dependency list, no Python version, and no model download instructions. It delegates all of that to docs.facefusion.io/installation. What it does give you is the invocation pattern and one command that exists specifically to fetch assets: force-download, described as "force automate downloads and exit." If your environment has no outbound network access at runtime, that command is the one to run during image build, before you invoke anything else. The first check after installation is python facefusion.py -v, which prints the program version, and python facefusion.py -h, which prints the help text reproduced in the README. From there, a single run is python facefusion.py run. For automation, python facefusion.py headless-run avoids the interface, and python facefusion.py batch-run handles multiple inputs. The queue path is more verbose: create, submit, then run, or create several and call job-submit-all followed by job-run-all. Note that the README shows no flags for selecting models, processors, input paths, or output paths. Those options exist somewhere in the program, since the help output is described as truncated in this material, but they are not in the README. Treat the documentation site as required reading, not optional.

Where the README stops and the risk starts

The gap between the README and a working deployment is the main thing to weigh. There is no list of supported processors, no description of the face detection or swapping models, no hardware requirements, no memory guidance, and no statement about how long a job takes. The benchmark command exists, so the project expects performance to vary by machine, but the README does not say what it measures or what a good result looks like. The licence is the second gap. The README displays a badge reading OpenRAIL-AS, while the repository metadata reports the licence as NOASSERTION. Those are not contradictory exactly, but they mean the same thing for a decision: no standard OSI licence identifier is being asserted by the repository. OpenRAIL-style licences typically carry use restrictions rather than granting unrestricted rights, so if FaceFusion would sit inside a commercial product or a redistributed bundle, read the actual licence text before you build on it. This is not legal advice, and the badge is not the licence file. A third limitation is structural: the README shows a CLI and nothing else. There is no documented Python import path, so if you wanted to call the swap logic from your own application rather than shelling out, this material gives you no evidence that is supported.

FaceFusion against a general video pipeline

The obvious alternative is building the same result out of a general video processing pipeline plus a face detection model and a swap model of your choosing. The difference is not quality, it is where the decisions live. In that approach you own the frame extraction, the detection, the alignment, the blending, and the re-encoding, and you can swap any stage for a different model or a different library. FaceFusion collapses those stages behind run, headless-run, and batch-run, and exposes the sequencing as job steps instead of as your code. That is a real trade. You get a maintained ordering of stages and a queue with retry semantics (job-retry, job-retry-all) that you did not have to write. You give up the ability to inspect or replace an intermediate stage, because the README does not describe the pipeline at all. If your requirement is a single well-defined swap on a known input, the general pipeline is more work than it is worth. If your requirement is many jobs, restartable on failure, with a status you can list, the built-in queue is the reason to pick FaceFusion over assembling the parts yourself.

Maintenance, releases and upgrade cost

The release cadence visible in the material is active: 3.9.0 on 2026-09-03, preceded by 3.8.3 on 2026-09-01 and 3.8.2 on 2026-08-10. The patch releases landing two days before a minor release suggests fixes are shipped quickly and separately from feature work. The last push to master is dated 2026-09-10, a week after 3.9.0, so the default branch moves between tagged releases. For an operator, that means pinning matters. If you install from master you are tracking unreleased code, and the README gives no compatibility statement about job formats between versions. The job queue writes state somewhere on disk, and the material does not say where or whether that state survives an upgrade. Before upgrading a queue with drafted or queued jobs in it, clear it with job-delete-all or drain it with job-run-all, because a format change between 3.8 and 3.9 is not something the README rules out. The CI badge in the README points at a GitHub Actions workflow, and there is a coverage badge, so tests exist, but neither badge tells you what is covered. On licence cost: the OpenRAIL-AS badge is the only licence signal in the README, and the repository reports NOASSERTION, so the compliance work is yours to do before adoption, not after.

Who should install it and what to check first

FaceFusion fits a team that already runs Python tooling from a terminal, needs face swap or lip sync as a repeatable operation rather than a one-off, and wants a job queue with retry built in instead of writing one. The headless-run and batch-run commands are the ones that matter for that use, and job-run-all is the one that matters if you are feeding a queue. It does not fit someone who needs a permissive licence with no use restrictions, someone who wants to import a Python function rather than invoke a CLI, or someone who cannot install from a terminal, which the README itself acknowledges by pointing those users at a separate installer. Before adopting, verify the licence text behind the OpenRAIL-AS badge against your distribution model, run python facefusion.py -h on your installed version to see the options the README omits, and run force-download during image build if your runtime has no network access. The documentation site at docs.facefusion.io is where the model and processor details live; the README is a command index, and treating it as anything more will leave you guessing at the parts that decide whether the output is usable.

Editorial conclusion

Adopt FaceFusion if you need a scriptable face swap or lip sync pipeline and you are willing to read the docs at docs.facefusion.io before touching the CLI, because the README alone will not tell you which processors exist. Do not adopt it if you need a permissively licensed dependency, if you cannot use a terminal (the README itself says installation is not recommended for beginners), or if you need a documented Python API rather than a command line. Verify three things first: the exact terms behind the OpenRAIL-AS badge, the processor and model names available in your installed version, and whether job-run-all fits your queue instead of batch-run.

Official sources

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