pxl8 CLI

pxl8 is a simple command-line tool that turns images into pixel art with optional false-coloring using matplotlib colormaps.

Getting Started

Make sure you have Python 3.12+ installed, then install the required packages:

pip install pillow numpy matplotlib

or with uv:

uv add pillow numpy matplotlib

Download the pxl8.py script or clone this repo:

git clone https://github.com/fuseraft/pxl8
cd pxl8

Usage

Navigate to the directory containing the script and run:

python pxl8.py <image_path> [options]

Parameters

Parameter	Description
image_path	Path to the input image
--cmap CMAP, -c CMAP	Colormap name (e.g. viridis, plasma), 'gray' or 'none' (default: none)
--pixel-size N, -p N	Pixel block size (default: 16)
--out PATH, -o PATH	Output file path (default: pixelized_output.png)
--list-colormaps, -l	List all available matplotlib colormaps and exit

Examples

Basic pixelation (16px blocks, original colors):

python pxl8.py photo.jpg

Strong pixelation with viridis colormap:

python pxl8.py selfie.jpg -c viridis -p 8

Grayscale big pixels, custom output name:

python pxl8.py landscape.jpg -c gray -p 32 --out big-gray-landscape.png

List available colormaps:

python pxl8.py -l

Example output of me dabbing on Diamond Head using the ocean colormap 🌊:

Contributing

Contributions are welcome! Feel free to fork the repository and open a pull request with your improvements.

License

This project is open source and available under the MIT License.