Setup guide for Python

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
• Python: version 3.9 or later (3.9–3.14)
• pip: version 20.3+

Developer environment setup

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

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:

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 to construct mp.Image inputs from files and OpenCV frames.

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.

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 to format NumPy PCM arrays and AudioData.

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

from mediapipe.tasks.python import retrieval

Decision tasks

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

from mediapipe.tasks.python import decision

BaseOptions configuration

BaseOptions allows general configuration of MediaPipe Task APIs:

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:

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:

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:

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 or Stack Overflow for support from the community. To report bugs or make feature requests, file an issue on GitHub.

For help setting up your Python development environment, visit the Python developer's guide.