<br />

This page shows you how to set up your development environment to use MediaPipe
Tasks in your Python applications and notebooks.

## Supported platforms and versions

Building applications with MediaPipe Tasks requires the following development
environment resources:

- OS:
  - Desktop: Windows (`x86_64`, `arm64`), macOS (Apple Silicon `arm64`), Linux (`x86_64`, `aarch64`; `glibc >= 2.28`)
  - IoT / Custom Linux: Raspberry Pi OS 64-bit (`aarch64`) or custom builds using [Build Python wheel](https://developers.google.com/edge/mediapipe/solutions/build_python.md.txt)
- Python: version 3.9 or later (3.9--3.14)
- pip: version 20.3+

> [!NOTE]
> **Note:** If you are testing or experimenting with MediaPipe Tasks, consider using [Google Colab](https://colab.research.google.com/), a Python notebook environment that requires no local setup and runs directly in the browser.

## Developer environment setup

Create and activate a virtual environment, then install the `mediapipe` package
using `pip`:

```bash
python3 -m venv mp_env
source mp_env/bin/activate  # On Windows: mp_env\Scripts\activate
python -m pip install --upgrade pip
python -m pip install mediapipe
```

After installing the package, import MediaPipe into your Python script or
notebook:

```python
import mediapipe as mp
from mediapipe.tasks import python
```

## MediaPipe Tasks dependencies

MediaPipe Tasks provides five domain modules for vision, text, audio, retrieval,
and decision tasks. Depending on the MediaPipe Task used by your application,
import the corresponding module into your Python project.

### Vision tasks

The MediaPipe Tasks vision module contains tasks that handle image, video, and
livestream inputs (such as Hand Landmarker, Face Landmarker, Pose Landmarker,
Object Detector, and Image Segmenter). See
[Prepare vision input data](https://developers.google.com/edge/mediapipe/solutions/prepare_data.md.txt#vision) to
construct `mp.Image` inputs from files and OpenCV frames.

```python
from mediapipe.tasks.python import vision
```

### Text tasks

The MediaPipe Tasks text module contains tasks that classify, detect language,
embed, proofread, and summarize text strings.

```python
from mediapipe.tasks.python import text
```

### Audio tasks

The MediaPipe Tasks audio module contains tasks that classify sound events,
transcribe speech, and synthesize speech audio. See
[Prepare audio input data](https://developers.google.com/edge/mediapipe/solutions/prepare_data.md.txt#audio) to
format NumPy PCM arrays and `AudioData`.

```python
from mediapipe.tasks.python import audio
```

### Retrieval tasks

The MediaPipe Tasks retrieval module provides document chunking, local vector
stores, semantic retrieval for RAG (`SemanticRetriever`), and multimodal text,
image, and audio embeddings (`UniversalEmbedder`).

```python
from mediapipe.tasks.python import retrieval
```

### Decision tasks

The MediaPipe Tasks decision module evaluates structured choice schemas, boolean
conditions, and rubric scores (`DecisionMaker`).

```python
from mediapipe.tasks.python import decision
```

## BaseOptions configuration

`BaseOptions` allows general configuration of MediaPipe Task APIs:

| Option name | Description | Accepted values |
|---|---|---|
| `model_asset_buffer` | The model asset file contents in memory. | `bytes` |
| `model_asset_path` | The path of the model asset file to open and map into memory. | `str` |
| `delegate` | Selects CPU or GPU execution where supported by the platform and model. | `BaseOptions.Delegate.CPU` \| `BaseOptions.Delegate.GPU` |

## Packaging Python Tasks apps with PyInstaller

When packaging a Python Tasks app with PyInstaller, model files such as `.task`
bundles are not included automatically. If your app uses
`BaseOptions(model_asset_path=...)`, include the model file in the PyInstaller
bundle and resolve its path at runtime.

For example, use a helper that checks for PyInstaller's `sys._MEIPASS`
directory:

```python
import os
import sys

def resource_path(relative_path: str) -> str:
    base_path = getattr(sys, "_MEIPASS", os.path.abspath("."))
    return os.path.join(base_path, relative_path)
```

Then pass the resolved model path to `BaseOptions`. This example bundles a
[Pose Landmarker model](https://developers.google.com/edge/mediapipe/solutions/vision/pose_landmarker.md.txt#models)
saved next to the script as `pose_landmarker.task`:

```python
import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

model_path = resource_path("pose_landmarker.task")
base_options = python.BaseOptions(model_asset_path=model_path)
options = vision.PoseLandmarkerOptions(base_options=base_options)

with vision.PoseLandmarker.create_from_options(options) as pose_landmarker:
    mp_image = mp.Image.create_from_file(resource_path("person.jpg"))
    result = pose_landmarker.detect(mp_image)
```

Bundle the model file and collect MediaPipe package files when building with
PyInstaller:

```bash
pyinstaller app.py \
  --add-data "pose_landmarker.task:." \
  --collect-all mediapipe \
  --hidden-import mediapipe.tasks.c
```

On macOS or Linux, the `--add-data` separator is `:`. On Windows, use `;`. For
macOS desktop apps, add `--windowed` to create an `.app` bundle.

## Troubleshooting

For help with technical questions related to MediaPipe, visit the
[discussion group](https://groups.google.com/forum/#!forum/mediapipe) or
[Stack Overflow](https://stackoverflow.com/questions/tagged/mediapipe) for
support from the community. To report bugs or make feature requests,
[file an issue on GitHub](https://github.com/google-ai-edge/mediapipe/issues).

For help setting up your Python development environment, visit the
[Python developer's guide](https://devguide.python.org/).