Install & Compatibility
Where this runs
tested against v0.5.4 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 19.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.4s · import 0.000s · 20MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
imutils
✓ import imutils
✗ import imutils
This quickstart demonstrates how to use `imutils.resize` to scale an image while preserving its aspect ratio. It first creates a dummy image (you'd typically load one with `cv2.imread`) and then resizes it to a specified width. Both the original and resized images are displayed using OpenCV's `imshow` function.
import cv2
import imutils
import numpy as np
# Simulate reading an image (replace with cv2.imread('path/to/image.jpg'))
# For demonstration, create a dummy black image (BGR format)
image = np.zeros((300, 500, 3), dtype="uint8")
cv2.putText(image, "Original Image", (100, 150), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)
# Use imutils.resize to resize the image while maintaining aspect ratio
resized_image = imutils.resize(image, width=150)
# Display original and resized images
cv2.imshow("Original", image)
cv2.imshow("Resized (width=150)", resized_image)
cv2.waitKey(0)
cv2.destroyAllWindows()
Debug
Known issues
breakingAs of late 2024, `imutils` has faced installation issues (e.g., `error: metadata-generation-failed`) for some users due to its reliance on `distutils` and `setup.py`, which are deprecated in newer Python/pip environments. The project also appears to be unmaintained, with no recent updates or fixes to these issues.fixConsider alternatives for specific functionalities or manually install dependencies if encountering build errors. Users have reported issues on GitHub related to `setuptools` not being available in the build environment.
affects: 0.5.4 and potentially older versions with newer pip/Python environments
gotchaImutils is a wrapper around OpenCV; therefore, `opencv-python` (or `opencv-contrib-python`) is a crucial, unlisted peer dependency. Trying to use `imutils` without `opencv-python` installed will result in `ImportError: No module named 'cv2'`.fixEnsure `opencv-python` is installed: `pip install opencv-python`.
affects: All versions
gotchaSimilar to OpenCV, `imutils` operations often rely on NumPy arrays. Forgetting to install `numpy` can lead to `ModuleNotFoundError: No module named 'numpy'` or other runtime errors.fixEnsure `numpy` is installed: `pip install numpy`.
affects: All versions
gotchaWhen displaying images using Matplotlib, remember that OpenCV (and by extension, `imutils` results) stores images in BGR format, while Matplotlib expects RGB. Displaying a BGR image directly with Matplotlib will result in incorrect color representation (e.g., blue appears red and vice-versa).fixConvert the image from BGR to RGB before displaying with Matplotlib: `image_rgb = cv2.cvtColor(image_bgr, cv2.COLOR_BGR2RGB)`.
affects: All versions
Upgrade
Version history
0.5.4latest on PyPI · released Jan 15, 2021
Audit
Dependencies
opencv-pythonrequiredImutils heavily relies on OpenCV for all its image processing functionalities. This (or `opencv-contrib-python`) must be installed separately.
numpyrequiredUsed for numerical operations on image arrays, a core dependency for image manipulation in Python.
matplotliboptionalOften used for displaying images, especially in development and debugging contexts.