Skip to main content
Help us improve PyPI by participating in user testing. All experience levels needed!

A Python module for extracting colors from images. Get a palette of any picture!

Project description is a Python library that lets you extract colors from images. Compared to other libraries, the colorgram algorithm’s results are more intense. is a port of colorgram.js, a JavaScript library written by GitHub user @darosh. The goal is to have 100% accuracy to the results of the original library (a goal that is met). I decided to port it since I much prefer the results the colorgram algorithm gets over those of alternative libraries - have a look in the next section.


Results of on a 512x512 image

Time-wise, an extraction of a 512x512 image takes about 0.66s (another popular color extraction library, Color Thief, takes about 1.05s).


You can install with pip, as following:

pip install

How to use

Using is simple. Mainly there’s only one function you’ll need to use - colorgram.extract.


import colorgram

# Extract 6 colors from an image.
colors = colorgram.extract('sweet_pic.jpg', 6)

# colorgram.extract returns Color objects, which let you access
# RGB, HSL, and what proportion of the image was that color.
first_color = colors[0]
rgb = first_color.rgb # e.g. (255, 151, 210)
hsl = first_color.hsl # e.g. (230, 255, 203)
proportion  = first_color.proportion # e.g. 0.34

# RGB and HSL are named tuples, so values can be accessed as properties.
# These all work just as well:
red = rgb[0]
red = rgb.r
saturation = hsl[1]
saturation = hsl.s

colorgram.extract(image, number_of_colors)

Extract colors from an image. image may be either a path to a file, or a file-like object. The function will return a list of number_of_colors Color objects.


A color extracted from an image. Its properties are:

  • Color.rgb - The color represented as a namedtuple of RGB from 0 to 255, e.g. (r=255, g=151, b=210).
  • Color.hsl - The color represented as a namedtuple of HSL from 0 to 255, e.g. (h=230, s=255, l=203).
  • Color.proportion - The proportion of the image that is in the extracted color from 0 to 1, e.g. 0.34.

Sorting by HSL

Something the original library lets you do is sort the colors you get by HSL. In actuality, though, the colors are only sorted by hue (as of colorgram.js 0.1.5), while saturation and lightness are ignored. To get the corresponding result in, simply do:

colors.sort(key=lambda c: c.hsl.h)
# or...
sorted(colors, key=lambda c: c.hsl.h)


If you find a bug in the, or if there’s a feature you would like to be added, please open an issue on GitHub.

If you have a question about the library, or if you’d just like to talk about, well, anything, that’s no problem at all. You can reach me in any of these ways:

To get a quick answer, Twitter is your best bet.


Project details

Release history Release notifications

This version
History Node


History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date (7.9 kB) Copy SHA256 hash SHA256 Wheel 2.7 Sep 16, 2016

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page