ansi-pixel

Convert images into true-color ANSI art for terminal banners, SSH previews, and Markdown.

Highlights

• 🎨 True-Color 24-Bit ANSI: Half-block terminal characters (▀ and ▄) pair vertical pixel rows to achieve double vertical resolution without square distortion.
• ⚡ Optimizer Sequence Compression: Aggressively collapses redundant foreground/background color escapes, achieving 70%+ byte reduction.
• 🖥️ Terminal Width Auto-Fitting: Auto-detects terminal width via shutil.get_terminal_size() when width is omitted.
• 🔄 UNIX Composability: Writes to stdout by default; fully supports pipes and reading from standard input (cat photo.png | ansi-pixel -).
• 🌐 Remote Image URLs: Convert remote images directly from HTTP/HTTPS URLs (ansi-pixel https://example.com/logo.png).
• 📦 Multi-Format Exporters: Output to raw ANSI, GitHub Markdown (```ansi), copyable Python snippets (art = [...]), JavaScript template strings, and styled HTML (<pre> & <span>).
• 🚫 NO_COLOR Standard: Adheres to the no-color.org specification and automatic non-TTY pipe detection.
• 🎛️ Resampling & Transparency: Multiple resampling filters (nearest, lanczos, bilinear), automatic alpha transparency, background trimming (--trim-bg), and hex chroma-keying (--chroma-key).

Installation

With pip

pip install ansi-pixel

With pipx (Standalone execution)

pipx run ansi-pixel logo.png

With uv

# Run ephemerally
uvx ansi-pixel logo.png

# Or add to your project
uv add ansi-pixel

With Homebrew (macOS / Linux)

brew install senurah/tap/ansi-pixel

Standalone Executable (Zero Dependencies)

Download prebuilt binaries for Linux, macOS, or Windows directly from GitHub Releases:

# Example on Linux x86_64
curl -L -o ansi-pixel https://github.com/senurah/ansi-pixel/releases/latest/download/ansi-pixel-linux-x86_64
chmod +x ansi-pixel
./ansi-pixel logo.png

Command-Line Usage

Basic Usage

Convert an image and auto-fit to your current terminal width:

ansi-pixel logo.png

Specify Output Width

Set an explicit character column width:

ansi-pixel logo.png -w 60

Read from Standard Input (Pipes)

Read piped image data using - or implicit pipe detection:

cat photo.png | ansi-pixel -
curl -s https://example.com/art.png | ansi-pixel -w 50

Load from Image URLs

Fetch and render remote images directly:

ansi-pixel "https://raw.githubusercontent.com/senurah/ansi-pixel/main/assets/logo.png" -w 40

Export to Files

Save the rendered art directly to a file using -o, --output:

# Save raw ANSI art for terminal banners (/etc/motd)
ansi-pixel logo.png -o banner.ans

# Save as GitHub-compatible Markdown (automatically inferred from .md extension)
ansi-pixel logo.png -o banner.md

# Save as an executable Python snippet
ansi-pixel logo.png -o art.py

# Save as styled HTML
ansi-pixel logo.png -o banner.html

Select Output Format

Explicitly choose a serialization format using -f, --format:

# Output GitHub-ready Markdown code block to stdout
ansi-pixel logo.png -f md

# Output copy-pasteable JavaScript template literal
ansi-pixel logo.png -f js

# Output HTML snippet
ansi-pixel logo.png -f html

Resampling Filters & Transparency

# Smooth downsampling for photographs using Lanczos filter
ansi-pixel photo.jpg --filter lanczos -w 80

# Strip near-white solid backgrounds and auto-crop borders
ansi-pixel icon.png --trim-bg

# Chroma-key a specific background color to transparent
ansi-pixel sprite.png --chroma-key "#00FF00"

Color Control & NO_COLOR

# Force ANSI colors even when redirecting or piping into tools like fzf
ansi-pixel --color logo.png | fzf --ansi

# Disable ANSI color sequences explicitly
ansi-pixel --no-color logo.png

# Respects the NO_COLOR standard automatically
NO_COLOR=1 ansi-pixel logo.png

CLI Options Reference

Python Library API Quickstart

ansi-pixel is fully usable as an imported Python library with strict typing and no external runtime dependencies beyond Pillow.

from PIL import Image
from ansi_pixel import OutputFormat, ResamplingFilter, image_to_ansi, render_image

# 1. Quick render to Markdown string
markdown_art = render_image("logo.png", width=40, format="md")
print(markdown_art)

# 2. Render to a styled, standalone HTML document
html_doc = render_image(
    "logo.png",
    width=50,
    format=OutputFormat.HTML,
    standalone=True,
    title="Terminal Logo",
)

# 3. Render copy-pasteable Python snippet
py_code = render_image("logo.png", width=30, format="py", var_name="banner")

# 4. Get raw list of ANSI lines for custom terminal loops
lines = image_to_ansi(
    "logo.png",
    width=36,
    filter=ResamplingFilter.LANCZOS,
    trim_bg=True,
)
for line in lines:
    print(line)

# 5. Accepts paths, PIL Images, raw bytes, BytesIO, and URLs
img = Image.open("logo.png")
ansi_text = render_image(img, width=40)

Output Formats Explained

Project Structure

ansi-pixel/
├── src/
│   └── ansi_pixel/
│       ├── __init__.py      # Public library API (render_image, image_to_ansi, etc.)
│       ├── cli.py           # Command-line interface entry point & argument parsing
│       ├── converter.py     # Image decoding, aspect math, and half-block generation
│       ├── optimizer.py     # ANSI escape sequence state tracking and compression
│       ├── render.py        # Top-level rendering and serialization engine
│       ├── py.typed         # PEP 561 inline type annotation marker
│       └── exporters/       # Target-specific serialization formats
│           ├── __init__.py  # Exporter registry & OutputFormat enum
│           ├── ansi.py      # Raw ANSI string exporter
│           ├── code.py      # Python and JavaScript code snippet exporters
│           ├── html.py      # Styled HTML <pre> and <span> exporter
│           └── markdown.py  # GitHub-compatible Markdown ```ansi code block exporter
├── tests/                   # Comprehensive pytest test suite (112 tests)
├── pyproject.toml           # PEP 621 packaging metadata, hatchling build, ruff & mypy configs
└── README.md

Development & Quality Assurance

Run test suite, type checker, and linters:

# Run unit tests
pytest

# Strict type checking
mypy src tests

# Code formatting and linting
ruff check src tests
ruff format --check src tests

License

This project is licensed under the terms of the MIT License.