MediaPipe and NumPy: distinguish dependency constraints from binary import failures

Scope and symptoms

Installation can fail during resolution, or a completed installation can fail while loading an extension. Read the actual MediaPipe distribution rather than applying a historical constraint to every release.

Search fragments; wording and context vary:

mediapipe
_ARRAY_API not found

Source-supported context

A 2024 issue in the MediaPipe project documents a NumPy-below-2 requirement for 0.10.15. That evidence concerns the historical combination; current applicability requires the official Python setup guidance and the installed release metadata. V04-MEDIAPIPE V04-MEDIAPIPEISSUE

Distinguish these cases

1. MediaPipe and another consumer declare incompatible NumPy ranges.

2. Installation completes but an extension fails with _ARRAY_API, dtype or another binary-interface error.

3. Imports work and the remaining failure concerns a node resource, image representation or model operation.

Suggested diagnostic sequence

This sequence is editorial guidance, not a diagnosis of your machine.

1. Record Python, MediaPipe, NumPy and node versions together with the resolver error or full traceback. Separate installation from runtime import.

2. Read Requires-Dist and run dependency checks for the actual release. Do not paste numpy<2 into a shared environment merely because it appears in an old discussion.

3. Isolate workloads with no supported common range. For binary failures, test a documented compatible rebuild or distribution in a copy instead of mixing unidentified binaries.

4. After imports work, run the author's minimal input and regress other retained NumPy consumers. Treat a newly exposed failure as a distinct stage rather than repeating downgrades.

Completion checks

Dependency metadata is consistent, relevant native imports work and both the minimal node and retained workflows pass.

Limits and cautions

This article does not claim that every MediaPipe version excludes NumPy 2. Constraints can change, and a passing metadata check does not establish ABI or functional compatibility.

Source review: 2026-09-22. No installation, GPU inference or user-environment repair was executed.

Original sources

• MediaPipe Python setup · 2026-09-22
• MediaPipe issue 5676: historical NumPy constraint · 2026-09-22

Related guides

• ModuleNotFoundError in ComfyUI even though the package is installed
• Keep a reproducible ComfyUI repair record without exposing secrets