facetorch: a Hydra-configured toolkit that packages face analysis models as torch.export artifacts

The packaging problem facetorch addresses

Face analysis in open source usually arrives as a repository per model: a checkpoint, a model definition file, and a preprocessing script that only matches the checkpoint it shipped with. If you need detection, landmarks, expression and action units in one service, you end up maintaining several such repositories and reconciling their input conventions. facetorch's stated aim is to curate those community models, package them as portable torch.export models, and integrate them into one toolkit. The audience is developers and researchers who need more than one face task in a single process and who would rather configure a pipeline than vendor model code. The library also carries an explicit ethics pointer to the European Commission's Ethics Guidelines for Trustworthy AI and warns that models may have limitations and biases, which is a reasonable signal about what the project thinks it is shipping.

What torch.export changes at inference time

The central mechanism is serialisation. Models are exported to the .pt2 format with torch.export, so the README states that no model source code is needed at inference time. That matters for deployment: you ship an artifact, not a Python package that has to import the original model class. The README also lists dynamic batch support and torch.compile compatibility as properties of the exported models. Configuration sits on top of this through Hydra and OmegaConf, so the pipeline shape (which models run, in what order, with which readers and processors) is expressed as configuration rather than as code you edit. Input handling is normalised: local paths, tensors, NumPy arrays, PIL images and bytes all enter through one canonical pipeline, and remote input is not implicit. It requires an explicit, bounded URLReader configuration, which keeps network fetching out of the default path.

Getting the RC installed without pulling a CUDA graph

The README is unusually direct about install order. Create a virtual environment, upgrade pip, install the CPU PyTorch cohort first, then install facetorch. The CPU commands are python -m pip install --index-url https://download.pytorch.org/whl/cpu "torch==2.13.0+cpu" "torchvision==0.28.0+cpu" followed by python -m pip install "facetorch==1.0.0rc3". The stated reason for the explicit index URL is that pip would otherwise select a multi-gigabyte CUDA dependency graph on a CPU host. For the validated CUDA 13.0 cohort the README substitutes --index-url https://download.pytorch.org/whl/cu130 with torch==2.13.0+cu130 and torchvision==0.28.0+cu130. Every matched pair from Torch 2.6/torchvision 0.21 through Torch 2.13/torchvision 0.28 is listed as supported. Plan for disk: the default model selection needs about 1.2 GB of cache data and at least 2 GB of free cache space while downloads are staged.

Docker, and why the example mounts input read-only

Docker is optional for the Python API. The compose example pins an immutable RC image tag through an environment variable rather than using latest: FACETORCH_DOCKER_TAG=1.0.0-rc.3 docker compose run --rm facetorch python /opt/facetorch/example.py /workspace/data/input/test.jpg --output /workspace/data/output/test.png. The GPU variant swaps the service name to facetorch-gpu and passes --profile gpu. The README notes that compose mounts data/input read-only and writes generated images to the facetorch-output volume, so the non-root container never needs write access to the source checkout. That is a small detail with a real consequence: the image cannot be used as a general file processor against arbitrary host paths without changing the mount configuration, and the example is the only entry point the material describes.

The v1 release candidate is not the default install

This is the limitation that will catch people. The documentation targets 1.0.0rc3 (Beta), and the README states plainly that bare pip install facetorch and the Docker latest tag remain on the stable 0.6.2 line during the RC soak. Conda-forge is described as asynchronous and must be verified separately; the README tells you not to use its unversioned install command for the RC and to wait until the feedstock displays 1.0.0rc3 before pinning. So a reader who follows the obvious install command gets a different API from the one documented here, and there is a v0.6.x migration guide in the repository precisely because the two differ. The platform matrix is similarly narrow: Linux x86-64 is the official v1 candidate platform, while Windows, macOS, ARM and Apple MPS are experimental. If your target is an M-series laptop or a Windows workstation, you are outside the supported surface.

Model rights, manifests and the cost of adding a model

The extensibility story has a governance layer that most libraries of this kind do not have. Custom readers, processors and configurations can be supplied directly, which is the ordinary extension path. Adding a hosted model to the built-in defaults is different: it requires an immutable manifest entry, validation evidence, provenance, and model-rights approval. That is a deliberate gate, and it means the built-in model set grows slowly and cannot be extended by a pull request that only adds a checkpoint URL. The trade-off is visible in both directions. You get a curated set with documented provenance, and you do not get to drop in whatever model you found last week without going through the process. The README points to a separate model compatibility and governance document for the current model-rights gates, so the specifics live outside the README and will change over time.

Where facetorch is the wrong pick, and what to use instead

If you need exactly one task, say face detection on a stream of frames, facetorch's value proposition does not apply. Its reason to exist is curating several models behind one configuration and one input pipeline. A single-purpose library such as MediaPipe Face Detection or a direct torchvision model call gives you a smaller dependency surface, no Hydra config layer, and no model cache to stage. The difference in approach is concrete: facetorch exports models to .pt2 and drives them from OmegaConf configuration with a governed default set, whereas a direct library call leaves model loading, preprocessing and versioning to your own code. The first is better when you have several face tasks and want the wiring handled; the second is better when you have one task and want to read the whole call stack in a single file. Neither is universally correct, but the second is clearly the wrong choice to replace with the first.

Licence and the maintenance surface you inherit

facetorch is Apache-2.0, which permits commercial use and modification with the usual notice and patent terms. That covers the library. It does not automatically cover the weights of the curated models, which is exactly why the project requires model-rights approval before a model enters the built-in defaults, and why the README directs you to the governance document for current gates. Check the provenance of each model you enable rather than assuming the repository licence settles it; this is not legal advice, and the model-rights document is the place to look. On maintenance cost, the material shows a project that pins hard: Python >= 3.10 and < 3.13, a matched torch and torchvision pair, an explicit index URL, and a stated cache budget. Upgrading means moving both torch and torchvision together within the documented matrix and re-verifying that the exported .pt2 artifacts still load, since the RC line is still moving through release candidates rather than sitting on a final release.

Editorial conclusion

Adopt facetorch if you are on Linux x86-64, can pin torch and torchvision to a matched pair from the documented matrix, and want face analysis models as .pt2 artifacts rather than as source trees you reimplement. Do not adopt it for Windows, macOS, ARM or Apple MPS work, and do not treat bare pip install facetorch or the Docker latest tag as the v1 API, since both stay on the 0.6.2 line during the RC soak. Before committing, verify that 1.0.0rc3 is actually visible on PyPI, that the conda-forge feedstock shows the same version, and that you have at least 2 GB of free cache space for the roughly 1.2 GB default model download.

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. tomas-gajarsky/facetorch on GitHub