Registry / ai-ml / mtcnn
library1.0.0pypypi✓ verified 29d ago

The `mtcnn` library provides a Python implementation of the Multi-task Cascaded Convolutional Networks (MTCNN) for robust face detection and alignment. It is currently at version 1.0.0, supporting Python >= 3.10 and TensorFlow >= 2.12. Releases are infrequent, indicating a mature and stable codebase.

pip install mtcnn
INSTALL
IMPORT
SIG · MTCNN
M
mtcnn
ai-mlpythonv1.0.0
Install
3.4s avg
Import
—
Disk
91MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
build_error
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 3.4s · import 0.000s · 28MB
91MB installed
● package 91MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MTCNN
✓ from mtcnn import MTCNN
✗ from mtcnn import MTCNN

This quickstart demonstrates how to load an image (using OpenCV, converting to RGB), initialize the MTCNN detector, and use `detect_faces` to find faces and their keypoints. The output `faces` is a list of dictionaries, where each dictionary contains the bounding box, confidence score, and facial keypoints.

import cv2 from mtcnn.mtcnn import MTCNN # Example image (replace with your path or download one) # For demonstration, we'll create a dummy image if file not found try: img_path = 'sample_image.jpg' # Replace with a path to a real image img = cv2.imread(img_path) if img is None: # Create a blank image with a simple 'face' if sample_image.jpg not found print(f"Warning: '{img_path}' not found. Creating a dummy image.") img = 255 * (cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (50, 50))) img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR) # Add a simple rectangle to simulate a face cv2.rectangle(img, (100, 100), (200, 200), (0, 0, 255), 2) except Exception as e: print(f"Error loading image or creating dummy: {e}") # Fallback to a completely black image if even dummy creation fails img = (255 * (cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (50, 50)))) img = cv2.cvtColor(img, cv2.COLOR_GRAY2BGR) # MTCNN expects RGB images, OpenCV loads BGR by default img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB) # Initialize the MTCNN detector detector = MTCNN() # Detect faces in the image faces = detector.detect_faces(img_rgb) # Print detected faces (each face is a dict with 'box', 'confidence', 'keypoints') for face in faces: print(face) # Optional: Draw bounding boxes and keypoints on the original image # for face in faces: # x, y, width, height = face['box'] # cv2.rectangle(img, (x, y), (x + width, y + height), (0, 255, 0), 2) # for key, value in face['keypoints'].items(): # cv2.circle(img, value, 2, (0, 0, 255), 2) # cv2.imshow('Detected Faces', img) # cv2.waitKey(0) # cv2.destroyAllWindows()
Debug
Known issues
breakingThe `mtcnn` library (v1.0.0 and later) explicitly requires Python 3.10 or newer due to `tensorflow` dependency constraints.
fix
Ensure your Python environment is version 3.10 or later. Consider using `pyenv` or `conda` to manage Python versions.
affects: All versions (v1.0.0+)
breakingOlder versions of `mtcnn` (prior to v1.0.0) may not be fully compatible with TensorFlow 2.x and its API changes. Version 1.0.0 introduced specific compatibility fixes.
fix
Upgrade `mtcnn` to version 1.0.0 or later to ensure compatibility with TensorFlow 2.x (specifically >=2.12 as per PyPI).
affects: <1.0.0
gotchaChanges in `numpy` (specifically `allow_pickle=False` by default in `numpy.load()` for security reasons) could cause issues when loading MTCNN's internal pre-trained models if `mtcnn` is older than v1.0.0. Version 1.0.0 addressed this internally.
affects: <1.0.0
gotchaThe `detect_faces` method expects input images to be in RGB format. If you load images using OpenCV (`cv2.imread`), they are typically in BGR format and will need conversion.
fix
After loading with OpenCV, convert the image using `img_rgb = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2RGB)`.
affects: All versions
gotchaThe first time `MTCNN` is initialized, it will automatically download pre-trained model weights from the internet. This requires an active connection and can introduce a delay on the initial run.
fix
Ensure internet connectivity during the first initialization. Subsequent runs will use the cached models.
affects: All versions
gotchaMTCNN leverages TensorFlow, so its performance is highly dependent on the TensorFlow installation. For significant speed improvements, ensure you have `tensorflow[and-cuda]` (or `tensorflow-gpu` for older versions) installed and a compatible GPU available.
fix
Install TensorFlow with GPU support if your hardware allows. Otherwise, be aware that CPU-only inference will be considerably slower.
affects: All versions
Upgrade
Version history
1.0.0latest on PyPI · released Oct 8, 2024
Audit
Dependencies
tensorflowrequiredBackend for neural network operations; requires >=2.12.
numpyrequiredFundamental package for numerical computing.
opencv-pythonoptionalCommonly used for image loading and preprocessing (e.g., cv2.imread, cv2.cvtColor).
Agent activity
16 hits · last 30 days
node
14
Anthropic
1
Resources