Registry / data / colorthief

colorthief

JSON →
library0.2.1pypypi✓ verified 87d ago

Colorthief is a minimalistic Python module (version 0.2.1) for extracting the dominant color or a representative color palette from an image. It relies on the Pillow library for image processing and uses a modified median cut quantization algorithm. While it hasn't seen recent updates, it remains functional for basic color extraction tasks.

pip install colorthief
INSTALL
IMPORT
SIG · COLORTHIEF
C
colorthief
datapythonv0.2.1
Install
2.3s avg
Import
69ms
Disk
35MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.1 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.072s · 37.3MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.3s · import 0.066s · 38MB
35MB installed
● package 35MB
Code
Verified usage

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

ColorThief
from colorthief import ColorThief

This quickstart demonstrates how to create a `ColorThief` object from an image file, extract its dominant color, and generate a color palette. It includes an example of creating a dummy image for easy testing.

import os # NOTE: Pillow is a required dependency for colorthief. # Ensure it's installed: pip install Pillow try: from PIL import Image from colorthief import ColorThief # Create a dummy image for demonstration if it doesn't exist # In a real scenario, replace 'temp_image.png' with your image file path. dummy_image_path = "temp_image.png" if not os.path.exists(dummy_image_path): # Create a simple image with a dominant red color img = Image.new('RGB', (100, 100), color = 'red') img.save(dummy_image_path) print(f"Created a dummy image: {dummy_image_path}") # Initialize ColorThief with your image file path color_thief = ColorThief(dummy_image_path) # Get the dominant color (RGB tuple) # quality=1 provides the highest quality but is slower. dominant_color = color_thief.get_color(quality=1) print(f"Dominant color (RGB): {dominant_color}") # Get a color palette (list of RGB tuples) # color_count: desired number of colors in the palette # quality: higher numbers are faster but lower quality palette = color_thief.get_palette(color_count=6, quality=10) print(f"Color palette (RGB): {palette}") # To clean up the dummy image after use: # os.remove(dummy_image_path) except ImportError as e: if "Pillow" in str(e): print("Error: Pillow is not installed. Please install it with 'pip install Pillow'.") else: print(f"An import error occurred: {e}") except FileNotFoundError: print(f"Error: The image file '{dummy_image_path}' was not found.") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
deprecatedThe `colorthief` library (version 0.2.1) has not been updated since February 2017. While it remains functional, more actively maintained and faster alternatives like `fast-colorthief` or `modern_colorthief` are available and recommended for new projects or performance-critical applications.
fix
For new projects or improved performance, consider `pip install fast-colorthief` or `pip install modern_colorthief` and adjust imports/API calls accordingly.
affects: <=0.2.1
gotchaThe `quality` parameter in `get_color()` and `get_palette()` significantly impacts both processing speed and the perceived accuracy of the extracted colors. A `quality` of 1 offers the highest precision but is the slowest, while larger numbers (e.g., 10 or more) provide faster results at the cost of potential visual accuracy.
fix
Experiment with different `quality` values. For the most visually accurate dominant color, use `quality=1`. For a faster, less precise palette, increase the `quality` value.
affects: <=0.2.1
gotchaWhen passing a file object instead of a file path to `ColorThief`, the object must be opened in binary mode (`'rb'`) and implement `read()`, `seek()`, and `tell()` methods.
fix
Ensure file objects are opened in binary mode (e.g., `with open('image.jpg', 'rb') as f: color_thief = ColorThief(f)`).
affects: <=0.2.1
Errors
Common errors & fixes
ImportError: cannot import name ColorThief from 'colorthief'
The `colorthief` package or its dependencies (like Pillow) were not installed correctly, or there's an environment conflict preventing proper import.
fix
First, ensure `Pillow` is installed (`pip install Pillow`). Then, try reinstalling `colorthief` by running `pip uninstall colorthief` followed by `pip install colorthief`. Check your Python environment for conflicts.
Colorthief / PIL is returning wrong values (inaccurate colours)
The median cut algorithm used by `colorthief`, especially with higher `quality` settings, might not always align perfectly with human visual perception of 'dominant' color. Also, some images naturally lack a single clearly dominant color.
fix
Adjust the `quality` parameter to `1` for the highest accuracy, though this will be slower. For images with complex color distributions, consider increasing the `color_count` for the palette or exploring alternative libraries like `fast-colorthief` which might offer different quantization algorithms.
Upgrade
Version history
0.2.1latest on PyPI · released Feb 9, 2017
Audit
Dependencies
PillowrequiredRequired for image loading and processing.
Agent activity
26 hits · last 30 days
node
24
OpenAI (training)
1
Resources
colorthief — pip install colorthief · libregistry