Automatic color palette detection
Python Makefile
Latest commit f83e59f Jun 2, 2015 @dhotson dhotson Merge pull request #24 from dset0x/optimizations
Speed-related optimizations
Failed to load latest commit information.
colorific Use `lru_cache` for color conversion May 27, 2015
tests Update test to match current output :P Oct 26, 2014
.gitignore Use make to drive building and testing. Mar 30, 2014
LICENSE.txt Add explicit ISC license. Jun 20, 2012 modularized colorific library, backward compatibility. May 5, 2013
Makefile Fix test for virtualenv. Oct 26, 2014
README.rst Bump version to 0.3.0. Oct 26, 2014
requirements_py3.pip Use `lru_cache` for color conversion May 27, 2015
tox.ini Use `lru_cache` for color conversion May 27, 2015



Image palette detection in Python modelled after Paul Annesley's color detector in PHP. colorific determines what the most important colors used in your image are, and if one of them is a background color.

by Dennis Hotson & Lars Yencken


The easiest way to install colorific is with Python's pip and virtualenv:

$ virtualenv colorific-sandbox
$ ./colorific-sandbox/bin/pip install colorific

You can then run colorific from ./colorific-sandbox/bin/colorific.


colorific is meant to run in a streaming manner. You can run it on a single image by echo'ing in the image:

$ echo myimage.png | colorific
myimage.png #3e453f,#2ea3b7,#bee6ea,#51544c,#373d38 #ffffff

Each input line should be a filename. Each output line will be a tab-delimited string containing the filename, major colors in order, and (optionally) a detected background color.

To run on an entire directory tree of images:

$ find . -name '*.jpg' | colorific

For a small amount of images, colorific can also be invoked with the image file names provided as arguments:

$ colorific myimage.png
myimage.png #3e453f,#2ea3b7,#bee6ea,#51544c,#373d38 #ffffff

You can also get a rendered palette with hex codes for each image with the -o argument:

$ colorific -o myimage.png
myimage.png #3e453f,#2ea3b7,#bee6ea,#51544c,#373d38 #ffffff
$ ls
myimage.png  myimage_palette.png

You can use an experimental multiprocessing mode with the -n argument. For example, to run the same example using 8 processes:

$ find . -name '*.jpg' | colorific -p 8

You can also get usage information by running colorific --help.


Here's a concrete example of use. This is the NASA Ares logo:

Let's run palette detection on it:

$ echo 500px-NASA-Ares-logo.svg.png | colorific
500px-NASA-Ares-logo.svg.png  #0065b9,#bbd6ec,#ff0000

These correspond to the colors:

Note that black and white have been stripped away, and minor colors introduced through antialiasing are not present.



  • Python 3 support
  • Bump colormath version to 2.0.2


  • Use the recent 1.7.8 Pillow release instead of the master branch
  • Pin the colormath to 1.0.9 or earlier, given API changes in newer code


  • Project renamed to colorific
  • Tuning around quantization and color merging
  • Use patched Pillow dependency to avoid segmentation fault bug
  • Support for outputting a palette file per image


  • Tuning around background color, similarity thresholds for merging, and minimum saturation
  • Make an importable module


  • Functional palette detection