> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# MediaPipe: Face Detection in ComfyUI

> Learn how to use MediaPipe Face Detection in ComfyUI to detect faces and extract facial landmarks, bounding boxes, and region masks from images

<Tip>
  <Tabs>
    <Tab title="Portable or self deployed users">
      Make sure your ComfyUI is updated.

      * [Download ComfyUI](https://www.comfy.org/download)
      * [Update Guide](/installation/update_comfyui)

      Workflows in this guide can be found in the [Workflow Templates](/interface/features/template).
      If you can't find them in the template, your ComfyUI may be outdated. (Desktop version's update will delay sometime)

      If nodes are missing when loading a workflow, possible reasons:

      1. You are not using the latest ComfyUI version (Nightly version)
      2. Some nodes failed to import at startup
    </Tab>

    <Tab title="Desktop or Cloud users">
      * The Desktop is base on ComfyUI stable release, it will auto-update when there is a new Desktop stable release available.
      * [Cloud](https://cloud.comfy.org) will update after ComfyUI stable release.

      So, if you find any core node missing in this document, it might be because the new core nodes have not yet been released in the latest stable version. Please wait for the next stable release.
    </Tab>
  </Tabs>
</Tip>

[MediaPipe](https://github.com/google-ai-edge/mediapipe) is Google's open-source machine learning solution for real-time perception. In ComfyUI, MediaPipe Face Detection provides **BlazeFace** detection, **FaceMesh v2** landmark estimation, and **ARKit-52 blendshapes** — all in a single unified workflow.

MediaPipe Face Detection is natively supported in ComfyUI (PR [#14009](https://github.com/Comfy-Org/ComfyUI/pull/14009)), and the model weights are available under the [Apache 2.0 License](https://github.com/google-ai-edge/mediapipe/blob/master/LICENSE).

[MediaPipe GitHub](https://github.com/google-ai-edge/mediapipe) | [Comfy-Org Model Repository](https://huggingface.co/Comfy-Org/mediapipe)

### Key capabilities

* **Fast face detection** — BlazeFace-based detector with short (\~2 m) and full (\~5 m) range variants
* **478 facial landmarks** — dense FaceMesh v2 keypoints per detected face
* **ARKit-52 blendshapes** — real-time facial expression coefficients
* **Face region masks** — per-region masks for face oval, lips, eyes, and irises
* **Face bounding boxes** — outputs compatible with `DrawBBoxes` for bounding box visualization

> **Scope:** Face detection only — BlazeFace + FaceMesh v2 + ARKit blendshapes. This does not cover hand, pose, or holistic detection.

## MediaPipe Face Detection Workflow

### 1. Download the Workflow

Update your ComfyUI to the latest version, then go to `Workflow` → `Browse Templates` and find "Mediapipe: Image Face Detection" under the Utility category.

<Card title="Download JSON Workflow File" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_face_detection_mediapipe.json">
  Download workflow
</Card>

<Card title="Run on Comfy Cloud" icon="cloud" href="https://cloud.comfy.org/?template=utility_face_detection_mediapipe&utm_source=docs&utm_medium=referral&utm_campaign=mediapipe">
  Open in cloud
</Card>

<Card title="Download Sample Image" icon="image" href="https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/soft_neon_girl.png">
  Get the example input image for this workflow
</Card>

![MediaPipe Face Detection preview](https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/templates/utility_face_detection_mediapipe-1.webp)

### 2. Download the Model

The MediaPipe Face Detection model is hosted on the [Comfy-Org MediaPipe model repository](https://huggingface.co/Comfy-Org/mediapipe).

* [mediapipe\_face\_fp32.safetensors](https://huggingface.co/Comfy-Org/mediapipe/resolve/main/detection/mediapipe_face_fp32.safetensors)

Place it in the following directory structure:

```
📂 ComfyUI/
└── 📂 models/
    └── 📂 detection/
        └── mediapipe_face_fp32.safetensors
```

### 3. Using the Workflow

This workflow uses a **subgraph** node that orchestrates face detection, visualization, and mask generation. The subgraph exposes the following controls:

<Card title="Learn about Subgraph" icon="book-open" href="/interface/features/subgraph">
  This workflow uses Subgraph nodes for modular processing. Check out the Subgraph documentation to learn how to customize and extend the workflow.
</Card>

**Subgraph inputs:**

| Input                | Description                                                                                                           |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **image**            | Input image batch to analyze                                                                                          |
| **face\_landmarker** | Optional. Leave empty to use the built-in model loader. Connect an external `FACE_DETECTION_MODEL` output to override |

**Subgraph parameters:**

| Parameter              |              Default              | Description                                                                                                                                                                                               |
| ---------------------- | :-------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **model\_name**        | `mediapipe_face_fp32.safetensors` | Checkpoint in `ComfyUI/models/detection/`. If missing, download the model above                                                                                                                           |
| **detector\_variant**  |              `short`              | **short** — tuned for close/large faces (\~2 m range). **full** — covers smaller/farther faces (\~5 m), slower. **both** — runs both detectors and keeps whichever found more faces per frame (\~2× cost) |
| **num\_faces**         |                `1`                | Maximum faces to return per frame. `0` = no cap (return all detected). Range: 0–16                                                                                                                        |
| **custom\_face\_oval** |              `false`              | Include face-outline region in the mask output                                                                                                                                                            |
| **custom\_lips**       |              `false`              | Include lips in the mask (union with other enabled regions)                                                                                                                                               |
| **custom\_left\_eye**  |              `false`              | Include left eye region in the mask                                                                                                                                                                       |
| **custom\_right\_eye** |              `false`              | Include right eye region in the mask                                                                                                                                                                      |
| **custom\_irises**     |              `false`              | Include iris regions in the mask                                                                                                                                                                          |

Mask toggles use custom mode internally: only checked regions are filled; multiple ON regions are **unioned** into one mask per frame.

**Subgraph outputs:**

| Output              | Type             | Description                                                                                                                  |
| ------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **face\_landmarks** | `FACE_LANDMARKS` | Per-frame faces with 478 2D/3D landmarks, ARKit-52 blendshapes, mesh topology data — feeds into visualization and mask nodes |
| **bboxes**          | `BOUNDING_BOX`   | Face bounding boxes — compatible with `DrawBBoxes` node                                                                      |
| **mask**            | `MASK`           | Binary mask from the enabled region toggles                                                                                  |

### 4. Run the Workflow

1. Ensure the model file is placed in `ComfyUI/models/detection/`
2. Load an image in the `Load Image` node
3. Adjust detection parameters as needed
4. Click `Queue` or use `Ctrl(Cmd) + Enter` to run
5. The workflow outputs the mesh overlay, bounding boxes, and mask preview

## Community Resources

* [MediaPipe GitHub](https://github.com/google-ai-edge/mediapipe) — Upstream MediaPipe framework
* [Comfy-Org/mediapipe](https://huggingface.co/Comfy-Org/mediapipe) — Official ComfyUI model weights
* [ComfyUI Subgraph Guide](https://docs.comfy.org/interface/features/subgraph) — Learn how subgraphs work