Skip to content
Convert photos to pixel art at the command line.
Branch: master
Clone or download
Pull request Compare This branch is 1 commit ahead of nathanharper:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Sorry for the dumb title! I couldn't think of anything. This is a command line utility that converts a photo to "pixel art", i.e. a lower resolution version of the same image with a custom color palette.

The idea is that you can specify one of the built-in palettes to use with the -p flag, or you can load a custom palette with the -c flag. The palette files should be in a valid JSON subset consisting of ONE top-level array containing an arbitrary number of arrays that all have EXACTLY three elements, all integers from 0-255. These are representative of RGB values. You can set the pixel width/height of the monochrome blocks to be generated with the -b option. Default is to create 8x8 blocks.

Aside from some basic, tangential image manipulation features like auto-cropping and resizing, the main extra feature is the ability to generate custom color palette files with an input image. Run phixelgator with the -g flag to convert the input image into a color palette file that can then be used with the -c flag. It's not recommended that you use palette files created with very complex images, as extremely large color palettes are the biggest bottleneck in performance. If you just want all the original colors of the image available with a more pixelized look, you can just run it without the -p or -c flag.


I've tested this successfully on Ubuntu Linux, OSX, and Windows. Dependencies are python >= 2.7 and the python imaging library "PIL". It should work with older versions of python as well, but you'll have to install the argparse library separately. This should be enough on mac and linux:
sudo easy_install PIL 
sudo easy_install argparse

On Windows, you can just get the installers from the site or whatever people do on Windows :P

Once that stuff is done, checkout the repo, and make sure it's executable:

git clone
cd phixelgator
chmod +x
./ -h

That's it! The last line in there should print the help info, which should be very up-to-date. You can also check out the bash scripts in the "tests" directory if you want to see some examples.


Here's a before and after of my cat using the Atari 2600 color palette.

Then you do a little... -b4 -p atari2600 ernie.jpg atari2600.png

And voila!

Here are the other default palettes.

Apple II

` -b4 -p appleii ernie.jpg appleii.png`

Commodore 64

` -b4 -p commodore64 ernie.jpg commodore64.png`


` -b4 -p contra ernie.jpg contra.png`


` -b4 -p gameboy ernie.jpg gameboy.png`


` -b4 -p grayscale ernie.jpg grayscale.png`


` -b4 -p hyrule ernie.jpg hyrule.png`


` -b4 -p intellivision ernie.jpg intellivision.png`


` -b4 -p kungfu ernie.jpg kungfu.png`

Super Mario Bros.

` -b4 -p mario ernie.jpg mario.png`


` -b4 -p nes ernie.jpg nes.png`


` -b4 -p sega ernie.jpg sega.png`


` -b4 -p tetris ernie.jpg tetris.png`

Mileage may vary depending on the palette you used, the colors used in the original image, the size of the original image, and the block size selected. All the samples above are using 4x4 monochrome blocks, but in many cases the default 8 will suffice.


This tool is *heavily* inspired by a site (which is now down) that was created by:
John Lee and Ethan Levy
You can’t perform that action at this time.