> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-nav-cta-ab-test-try-cloud-free.mintlify.site/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="Local 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.

      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="Cloud users">
      * [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

<h3 id="utility_face_detection_mediapipe">
  Mediapipe: Image Face Detection
</h3>

Input an image and detect up to 6 facial landmarks per face, enabling ultrafast multi-face detection.

<img src="https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/templates/utility_face_detection_mediapipe-1.webp" alt="Mediapipe image face detection workflow preview" />

<CardGroup cols={2}>
  <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 Comfy Cloud
  </Card>

  <Card title="Download Workflow" icon="download" href="https://github.com/Comfy-Org/workflow_templates/blob/main/templates/utility_face_detection_mediapipe.json">
    Download JSON or search "Mediapipe: Image Face Detection" in Template Library
  </Card>
</CardGroup>

**Input materials**

Upload this file to the matching `LoadImage` node:

<CardGroup cols={2}>
  <Card title="soft_neon_girl.png" icon="image" href="https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/soft_neon_girl.png">
    `LoadImage` node 5 · `soft_neon_girl.png`
  </Card>
</CardGroup>

<div style={{display: 'grid', gridTemplateColumns: 'repeat(2, minmax(0, 1fr))', gap: '1rem', alignItems: 'start'}}>
  <img src="https://raw.githubusercontent.com/Comfy-Org/workflow_templates/main/input/soft_neon_girl.png" alt="Input image" style={{width: '100%', height: 'auto', objectFit: 'contain'}} />
</div>

### 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.

### 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/blob/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