Facetorch: the release candidate is tagged, the pip package is still on 0.6.2

The rc tags exist, the published package does not

The install section opens with a warning that reframes every command after it. This branch prepares 1.0.0rc4 as a beta, and that version is not yet published. The versioned install and container commands are meant to be used only after its approved publication on PyPI and Docker Hub. Meanwhile bare `pip install facetorch` and the Docker `latest` tag remain on the stable 0.6.2 line for the duration of the release candidate soak, conda-forge is asynchronous and has to be verified separately, and none of those unpinned routes can be assumed to expose the v1 API shown in the documentation. The GitHub releases tell the other half of the story: v1.0.0-rc.4 was tagged on 2026-09-23, after rc.3 on 2026-09-03 and rc.2 on 2026-09-01, and the last push to main came on 2026-09-24. A tag on GitHub is therefore not evidence that the code has reached an index. Two image repositories carry the container side of that same gap, `tomasgajarsky/facetorch` and `tomasgajarsky/facetorch-gpu`, and Docker is described as optional for the Python API rather than as the primary interface. The production image does contain the example script, which is what makes the one-line Compose runs below possible, but nothing in the project forces you through a container to use the library.

Install torch first or pip will pull the CUDA graph

The recommended sequence puts PyTorch in place before Facetorch, and the stated reason is disk and time rather than correctness. On a CPU host, letting pip resolve torch freely can select a multi-gigabyte CUDA dependency graph, so the CPU cohort is installed explicitly first from the PyTorch CPU index:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --index-url https://download.pytorch.org/whl/cpu \
  "torch==2.13.0+cpu" "torchvision==0.28.0+cpu"
python -m pip install "facetorch==1.0.0rc4"

For hardware that has CUDA 13.0, the same two lines are replaced by the cu130 index and the `+cu130` builds. Torch 2.13.0 with torchvision 0.28.0 is the recommended pair for new installations, and every matching pair from Torch 2.6 with torchvision 0.21 up to Torch 2.13 with torchvision 0.28 is supported. The manifest encodes that window as `torch>=2.6,<2.14` and `torchvision>=0.21,<0.29`, so the declared range and the documented matrix agree.

The default model set wants 1.2 GB of cache and 2 GB free

Downloads are a first-class part of the setup rather than an afterthought. The default model selection needs approximately 1.2 GB of cache data, and at least 2 GB of free cache space while those downloads are staged, which is more than the final footprint because the temporary and completed copies coexist. The cache location is a plain environment variable, `FACETORCH_CACHE_DIR`, set to `/var/cache/facetorch` in both Compose services, and each service gets its own named volume for it. The download path itself runs through the declared dependencies: gdown and huggingface_hub cover hosted weights, requests covers plain fetches, and timm supplies vision backbones. Two small runtime packages sit alongside them for measurement rather than modelling, codetiming for elapsed-time accounting and python-json-logger for structured log lines, which is consistent with a library that exposes hooks for callers instrumenting their own pipelines. That cache figure also explains the split between CPU and GPU cache volumes in the Compose file, since the two cohorts are expected to accumulate their own copies.

Three Compose services, two cache volumes, one shared output

The Compose file defines three services and three volumes. `facetorch` is the CPU image with the CPU cache volume, `facetorch-gpu` is the GPU image with the GPU cache volume, and `facetorch-gpu-no-device` uses the same GPU image and the same GPU cache volume but reserves no hardware. All three mount `./data/input` at `/workspace/data/input` read-only and write generated images into the single `facetorch-output` volume, which is why the production image can run as a non-root user without write access to the source checkout. Every service pins `platform: linux/amd64`, so an ARM host runs these images under emulation rather than natively, matching the project's stance that Linux x86-64 is the official v1 candidate platform while Windows, macOS, ARM and Apple MPS are experimental. Results leave the container through an explicit copy, since `cat` on the output volume is the documented way to get a file back into the checkout:

FACETORCH_DOCKER_TAG=1.0.0-rc.4 docker compose run --rm facetorch \
  python /opt/facetorch/example.py /workspace/data/input/test.jpg \
  --output /workspace/data/output/test.png

The GPU variant of the same command runs the `facetorch-gpu` service and adds `--profile gpu`, writing to a separate output filename so a CPU and a GPU result can sit in the same volume without collision.

A GPU service with no device reservation is still shipping

The `facetorch-gpu-no-device` service deserves its own note, because its configuration looks like a leftover and behaves like a feature. It builds from `docker/Dockerfile.gpu`, uses the `tomasgajarsky/facetorch-gpu` image with the same default tag, mounts the same GPU cache volume and the same read-only input, and shares the output volume, but its definition carries no `deploy.resources.reservations` block. The GPU service that can actually use a card declares one, with `driver: nvidia`, `count: 1` and `capabilities: [gpu]`, and the run command for it adds `--profile gpu`. So the pair exists to give you the GPU image without a device claim, useful for staging or for pulling weights on a machine with no NVIDIA driver. The compose file does not say why, so treat the intent as unstated and pick based on whether your host actually has a GPU.

A hosted model needs a manifest entry and rights approval

Extensibility is deliberately split into two speeds. Custom readers, processors and configurations can be handed in directly, and input handling is deterministic across local paths, tensors, NumPy arrays, PIL images and raw bytes through one canonical pipeline; anything remote requires an explicit, bounded `URLReader` configuration rather than a permissive default. Adding a model to the built-in defaults is the slow path: it needs an immutable manifest entry, validation evidence, provenance and model-rights approval. The repository layout backs that up, with `model_defs/` and `model_cards/` directories and a `MODEL_NOTICE.md` that is registered alongside `LICENSE` in the manifest's license files. Model serialization is the other governed piece: models ship as torch.export programs in the `.pt2` format, so no model source code is needed at inference time, with dynamic batch support and torch.compile compatibility. Browsing the library before installing it is possible: a demo notebook is published for Colab, and the API reference is generated with pdoc3. What the project does not publish is a home page of its own, so the documentation set, the PyPI page, the conda-forge channel and the two Docker Hub repositories are the whole of its public surface.

Three V1 remediation documents and two lock systems

The root of the repository is unusually candid about process. `V1_GA_REMEDIATION_STATUS.md`, `V1_RELEASE_FRESH_REVIEW.md` and `V1_RELEASE_REMEDIATION_PLAN_DRAFT.md` sit next to the README for a library still at a release candidate, and `SECURITY.md`, `CHANGELOG.md` and `TESTING.md` complete the set. Reproducibility is handled by more than one tool at once: uv and `uv.lock` for Python packaging, conda-lock with both `conda-lock.yml` and `gpu.conda-lock.yml` for conda-forge, paired `environment.yml` and `gpu.environment.yml` files, plus Docker under `docker/`. The build system itself is pinned to exact versions, `setuptools==84.0.0` and `wheel==0.46.3`, and one development tool is frozen at `pdoc3==0.11.6`, which is what generates the API documentation. Configuration runs through Hydra with OmegaConf, both capped below their next minor, and instrumentation dependencies such as codetiming and python-json-logger sit in the runtime list rather than in development. The support matrix is declared in classifiers as well as in the readme: Beta development status, console environment, science and research plus end-user desktop audiences, POSIX Linux, and Python 3.10, 3.11 and 3.12 explicitly, which matches the `>=3.10,<3.13` requirement rather than implying support for the 3.13 release. The ethical framing is stated in the same breath as the platform list, pointing at the European Commission's Ethics Guidelines for Trustworthy AI and warning that the curated models carry limitations and potential biases that callers are expected to evaluate for their own use.

Editorial conclusion

Facetorch suits research and product teams on Linux x86-64 who want community face models behind one Hydra-configured API and who can pin an exact release candidate rather than tracking a moving line. Before you install anything, read the version note: the tagged candidates are not on PyPI, bare `pip install facetorch` gives you 0.6.2, and conda-forge lags independently, so an unpinned install will not match the v1 API in the documentation. Install torch from the CPU or CUDA index before the library so pip cannot choose a multi-gigabyte CUDA graph on a CPU host, and remember that fetching the default models needs about 1.2 GB of cache.

Frequently asked questions

Official sources

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