---

jpg2xlsx is a small Python CLI and library for generating .xlsx files from raster images. It is useful for pixel art experiments, spreadsheet demos, teaching, and weird outputs that are much more eye-catching than a normal spreadsheet should be.

Why this exists

• Converts images into native Excel workbooks.
• Works as both a CLI and an importable Python package.
• Uses a simple src/ layout, uv, ruff, tests, and GitHub Actions.
• Supports JPEG, PNG, BMP, GIF, and other formats that Pillow can read.

---

Install

With uv

uv tool install jpg2xlsx

With pip

pip install jpg2xlsx

---

CLI usage

Convert an image and write output.xlsx:

jpg2xlsx input.jpg output.xlsx

If you omit the output path, the tool writes next to the input file using the same stem:

jpg2xlsx assets/pixel-cat.png

Useful options:

jpg2xlsx input.png output.xlsx --cell-width 0.18 --cell-height 1.6 --overwrite

Compact large exports

This project writes one Excel cell per image pixel. That means file size grows quickly with image dimensions.

• A 512x512 image becomes 262,144 formatted cells.
• More cells means more worksheet XML inside the .xlsx file.
• More unique colors usually means more cell formats too.

So a large image producing a workbook around 1.5 MB is not unusual for this output model.

If you want smaller .xlsx files, reduce one or both of these before export:

• Total pixels with --max-dimension
• Color variety with --colors

Recommended commands:

jpg2xlsx image.png output.xlsx --max-dimension 256 --colors 64

jpg2xlsx image.png output.xlsx --max-dimension 128 --colors 32

jpg2xlsx image.png output.xlsx --max-dimension 384 --colors 128

Practical guidance:

• Use --max-dimension 128 --colors 32 when file size matters more than fidelity.
• Use --max-dimension 256 --colors 64 as a balanced default for big images.
• Use --max-dimension 384 --colors 128 when you want to preserve more detail.

Option reference:

• --max-dimension: downscales the image so its largest side matches the given value before generating the workbook.
• --colors: reduces the image palette to the given number of colors, from 1 to 256.

Run help:

jpg2xlsx --help

---

Running in development

If you are running from the source tree, prefer module or script entrypoint execution instead of calling the package directory directly.

Correct:

uv run jpg2xlsx input.png output.xlsx

uv run python -m jpg2xlsx input.png output.xlsx

Incorrect:

uv run python src/jpg2xlsx

That direct directory execution does not establish package context correctly in Python, so relative imports can fail.

---

Python usage

from jpg2xlsx import convert

convert("input.jpg", "output.xlsx")

You can also use the compacting options from Python:

from jpg2xlsx import convert

convert(
    "input.jpg",
    "output.xlsx",
    max_dimension=256,
    colors=64,
)

---

Development

uv sync --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pytest

---

Release flow

• CI runs lint, tests, and package builds on pushes and pull requests.
• Version bump workflows use Commitizen and update the changelog.
• Publish workflows build with uv and upload to PyPI or TestPyPI.

---

Contributing

See CONTRIBUTING.md for local setup and contribution guidelines.

Security

See SECURITY.md for vulnerability reporting.

License

This project is licensed under the MIT License.

---

---

Star History