celeb-detection-oss and GIPHY's 2,300 celebrity face model

A celebrity model, not a face recognition system for people

GIPHY describes the project as its open source celebrity detection deep learning model and code, and the claim is specific: a custom machine learning model able to discern over 2,300 celebrity faces with 98% accuracy.

Two details in that sentence matter. The first is that the model was trained to identify the most popular celebs on GIPHY, so the label set is a closed list of public figures rather than a general identity model. The second is that it can identify and make predictions for multiple faces across a sequence of images, like GIFs and videos, so the pipeline is built for animated and video frames rather than for a single photograph.

The stated goal was to build a deep learning model that could annotate GIPHY's most popular content as well as, or hopefully better than, similar models offered by major tech companies. The readme says the model and the training code were released to the public in hopes that others might build off the work, integrate the model into their own projects, or learn from the approach.

The project was developed by the GIPHY R&D team, and the readme credits four people by name: Nick Hasty, Ihor Kroosh, Dmitry Voitekh and Dmytro Korduban, each with a GitHub handle. There is a link to the GIPHY engineering blog for the longer story, and a hosted demo at celebrity-detection.giphy.com.

The complete list of celebrities recognised with the model is published in the repository as a labels file under `examples/resources/face_recognition/labels.csv`, which is the reference point for anyone who wants to know what the model can actually name.

The work directory convention, which is the real interface

The training and transfer learning experimentation pipeline is documented in terms of a directory layout, and that layout is the thing you have to get right.

The steps are: create a work directory to store the results of experiments, which does not have to be inside the project, then inside it create an experiment directory whose name must match the name of the related experiment Python file, for example an `example_experiment` directory for an `example_experiment.py` file. Then a `face_recognition` directory inside the work directory holding the weights for the MTCNN model, three files named `det1.npy`, `det2.npy` and `det3.npy` that can be copied from the Giphy pretrained resources archive. Then a `labels.csv` inside the experiment directory, and a `raw_dataset` directory inside the experiment directory holding a dataset of uncropped images arranged in one subdirectory per person.

The overall shape is:

- workdir
  - example_experiment
    - raw_dataset
      - Person1
        image1.jpg
        image2.jpg
        image3.jpg
        ...
      + Person2
      + Person3
      ...
    labels.csv
  - face_detection
    det1.npy
    det2.npy
    det3.npy

The `labels.csv` file has a simple two column structure, a label and an index, and the example in the readme shows entries like `Person1,0`, `Person2,1` and `Person3,3`.

The split between MTCNN weights in a shared `face_detection` directory and the per-experiment data is the interesting design decision. MTCNN is the face detection stage, the thing that finds faces in a frame, and the recognition stage works on the cropped results. Keeping the detector weights shared and the data and label mapping per experiment means you can start a new experiment without re-staging the detection model, and the label file travels with the data it describes.

One detail is worth flagging. The published label list uses the `Label,Index` structure, and the example in the readme skips index 2. If you point the training at the published celebrity list, the mapping between the label file and the directory names in `raw_dataset` is what defines your classes, and a mismatch there produces a model that trains cleanly and recognises nothing.

CPU or GPU is a source file edit, not a flag

Choosing where to run training is handled by editing a file, and the readme is upfront about it.

You need to change `requirements_cpu.txt` to `requirements_gpu.txt` in `setup.py`, or leave it as it is, and to mind changing the `tensorflow` version if necessary. That is the whole mechanism. There is no extra or build switch in the manifest, and the setup script itself reflects this, because it parses `requirements_cpu.txt` directly at build time:

requirements = parse_requirements('requirements_cpu.txt', session=False)

and then feeds those into `install_requires`.

That single line explains most of the friction in running this project today. The dependency set is chosen at packaging time by reading one of the two requirement files, so the CPU and GPU variants are two different builds of the same package rather than one package with an extra.

The repository layout confirms the split at the top level, with `requirements_cpu.txt` and `requirements_gpu.txt` both present, alongside `setup.py`, `model_training/`, `experiments/`, `examples/`, `workdir/`, a `Dockerfile`, a `docker-compose.yml` and a `.env.example`.

The instructions for the CPU path are otherwise conventional for a Python 3.6 era project. Create a virtual environment to localize dependencies if you want one, install the package with `pip install -e .`, copy `.env.example` to `.env` and fill in the missing values, then run the experiment script from the top level directory, for example `python experiments/example_experiment.py`.

The `.env.example` file shows the small set of variables involved: `EXPERIMENT_FILENAME`, `USE_GPU`, `TENSORBOARD_PORT`, `WORKDIR` and, for Docker only, `LOCAL_WORKDIR`.

The Docker path expects an NVIDIA container runtime

The container route is the more demanding of the two, and the readme is explicit about the prerequisites.

You need to install nvidia-docker2, then modify your `/etc/docker/daemon.json` to register the nvidia runtime as the default:

{
    "default-runtime": "nvidia",
    "runtimes": {
        "nvidia": {
            "path": "/usr/bin/nvidia-container-runtime",
            "runtimeArgs": []
        }
    }
}

Then you create your experiment, naming the file in the `CMD` section of the `Dockerfile`, copy `.env.example` to `.env`, and make sure you have changed the data directory and the TensorBoard port in `docker-compose.yml`.

Before running anything you have to explicitly activate three environment variables in your shell, since they are required during container launch: `TENSORBOARD_PORT`, `WORKDIR` and `LOCAL_WORKDIR`. The compose file consumes all three, mapping the port and mounting `${LOCAL_WORKDIR}` at `${WORKDIR}`.

The launch is either through compose:

docker-compose up --build

or with plain Docker commands, for example:

docker build -t celebrity-detection-model-train .
docker run --rm --volume $LOCAL_WORKDIR:$WORKDIR --env-file .env --runtime=nvidia --shm-size 8G -p $TENSORBOARD_PORT:$TENSORBOARD_PORT celebrity-detection-model-train

The `--shm-size 8G` is not incidental. Docker's default shared memory size is small, and a data pipeline that loads and batches images will fail on it, which is why both the compose file and the run command set it to 8gb.

The image itself is built on `ufoym/deepo:pytorch-py36`, a prebuilt deep learning image, with `libsm6`, `libxext6` and `libxrender-dev` added on top, and the working directory set to `/experiments`.

Trying the model out is a different path from training it

The inference side lives in the `examples/` directory, and the readme points there for downloading the model and testing it on your own GIFs and videos.

The example tree is organised by purpose: `download_model.py` for fetching the weights, `inference.py` for running detection, `app.py` as an application entry point, `media/` for sample input, `templates/` for something rendering, `resources/` holding the published files such as the celebrity label list, and its own `requirements.txt` and `.env.example`.

That separation is the right shape for the project, because the two halves have different dependencies. Training needs TensorFlow, the GPU stack and the container runtime; inference needs a pretrained checkpoint and the recognition code. Splitting them means someone who only wants to run the model does not have to install the training environment, and someone porting the approach to their own data does not have to fight the example scripts.

It also matches the stated goal of releasing the work so others can build on it. The training pipeline is the more valuable artefact for a researcher, and the inference example is the more accessible one for a developer who just wants to see what the model does.

The repository also ships a `model_training/` directory at the top level, alongside `requirements_cpu.txt` and `requirements_gpu.txt`, so the model code and the training harness are kept in separate trees from the examples.

A 2018 setup.py, a Python 3.6 base, and a licence that needs reading

Two things in the packaging metadata deserve a close look before you commit to this codebase.

The first is the age. The setup script parses requirements with a try on `from pip._internal.req import parse_requirements` and a fallback to `from pip.req import parse_requirements`, and the fallback path was removed from pip in later versions, so the script only installs on the pip versions that still had it. The classifier list has a single Python entry, `Programming Language :: Python :: 3.6`, the prerequisites say Python 3.6 or higher, and the Docker base image is the py36 tag. The readme notes that you may need to change the `tensorflow` version yourself, which is what you would expect from a project whose dependency stack predates the current TensorFlow releases.

The second is the licence, and it is genuinely ambiguous in the repository itself. The repository records MPL-2.0 and there is a `LICENSE` file at the root. But the setup script declares `license='Proprietary'` and adds the classifier `License :: Other/Proprietary License`, and the package name is `celebrity-detection-model-train` with the description Facial recognition model training. So the code in the repository is under the Mozilla Public License while the packaged distribution claims to be proprietary. That is a question for the copyright holders rather than something to resolve by reading, and it is exactly the kind of mismatch that should be settled before a team builds on it.

The development status classifier says `Development Status :: 3 - Alpha`, the version is 1.0.0, and the author contact is the Giphy R&D address. The repository publishes no GitHub releases, and the last push was on 2026-10-12.

For a project of this shape, the fair reading is that the code is a snapshot of a research effort rather than a maintained library, and it is best treated as a reference implementation to read and adapt rather than a dependency to pin.

Editorial conclusion

celeb-detection-oss fits a researcher or engineer who wants to run face recognition over GIF and video frames, to fine tune the model on a celebrity set of their own, or to study how GIPHY assembled a face detection and recognition pipeline with MTCNN. It is the wrong tool for a product that needs to identify people who are not celebrities, and the wrong tool for a modern stack, since the setup targets Python 3.6 and the packaging metadata still says Proprietary while the repository licence is MPL-2.0. Before you build on it, verify three things: that the pretrained weights still download, since the instructions point at an S3 archive, that you can get the environment to run, given the Python 3.6 requirement and the TensorFlow version juggling the readme describes, and how the `labels.csv` convention in the experiment directory interacts with the label list the project publishes. The code is MPL-2.0, the last push was on 2026-10-12, and the repository publishes no releases.

Frequently asked questions

Official sources

1. Giphy/celeb-detection-oss on GitHub
2. Issues
3. License: MPL-2.0
4. Project website
5. README