Registry / ai-ml / mtcnn
library1.0.0pypypi✓ verified 21d 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.93.13
musl
3.93.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.103.95 runs
build_error
glibc
py 3.103.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
9 hits · last 30 days
node
8
Resources
mtcnn — pip install mtcnn · libregistry