image2excel

Convert any image into an Excel spreadsheet where each cell is a pixel, colored to recreate the original image.

Installation

pip install image2excel

Or with uv:

uv add image2excel

Quick Start

Python API

from image2excel import im2xlsx

# Basic usage - creates photo.xlsx alongside the source image
im2xlsx("photo.png")

# Keep original size (no resizing)
im2xlsx("photo.png", resize=False)

# Resize while preserving aspect ratio
im2xlsx("photo.png", keep_aspect=True)

Command Line

# Convert an image
image2excel photo.png

# Skip resizing
image2excel photo.png --no-resize

# Preserve aspect ratio
image2excel photo.png --keep-aspect

How It Works

1. Opens the image and converts it to RGB
2. Optionally resizes to fit within 260x300 pixels (configurable)
3. Maps each pixel to an Excel cell with a matching background color
4. Sets the zoom to 10% so you can see the full picture

The output .xlsx file is saved next to the source image.

API Reference

im2xlsx(file, *, resize=True, keep_aspect=False) -> Path

Parameter	Type	Default	Description
file	str | Path	-	Path to the source image
resize	bool	True	Shrink images larger than 260x300
keep_aspect	bool	False	Preserve aspect ratio when resizing

Returns: Path to the generated .xlsx file.

Development

# Clone and install with dev dependencies
git clone https://github.com/michelkluger/excel2image.git
cd excel2image
uv sync --dev

# Run tests
uv run pytest

# Lint and format
uv run ruff check .
uv run ruff format .

# Type check
uv run ty check src/

License

MIT