asciinator 0.1.0

Convert images to ANSI-colored ASCII/Unicode art in the terminal

asciinator

Convert images to ANSI-colored ASCII/Unicode art in your terminal.

Supports three rendering modes:

• halfblock (default) — Unicode upper-half-block (▀) with 24-bit foreground and background color. Packs two image rows per terminal line, doubling vertical resolution.
• shade — Unicode shade blocks (█▓▒░) with 24-bit foreground color.
• ascii — Classic ASCII ramp (@%#*+=-:.) with 24-bit foreground color.

Install

pip install asciinator

For SVG input support:

pip install 'asciinator[svg]'

Or with uv:

uv tool install asciinator

Usage

asciinator path/to/image.png
asciinator logo.jpg --mode shade
asciinator photo.png --mode ascii --chars "@%#*+=-:." --width 120
asciinator icon.svg --saturation 1.4 -o icon.ansi

Options

Option	Description
--mode {ascii,shade,halfblock}	Output mode (default: halfblock)
--chars CHARS	Custom character ramp, darkest→brightest (ignored for halfblock)
--width N	Output width in characters (default: terminal width)
--saturation F	Color saturation multiplier (default: 1.0; >1 is more vivid)
-o FILE, --output FILE	Also write output (with ANSI codes) to this file

Output is auto-sized to fit the terminal height. Your terminal must support 24-bit true color (most modern terminals do).

Development

This project uses uv for dependency management and builds.

# Run from source
uv run asciinator path/to/image.png

# Build wheel + sdist into dist/
uv build

# Install the built wheel for local smoke testing
uv tool install --from dist/asciinator-0.1.0-py3-none-any.whl asciinator

Publishing

Build artifacts first:

uv build

Dry-run on TestPyPI:

# Create a token at https://test.pypi.org/manage/account/token/
uv publish --publish-url https://test.pypi.org/legacy/ \
           --token pypi-<TESTPYPI_TOKEN>

# Verify install from TestPyPI
uv tool install --index-url https://test.pypi.org/simple/ \
                --extra-index-url https://pypi.org/simple/ \
                asciinator

Publish to real PyPI:

# Create a token at https://pypi.org/manage/account/token/
uv publish --token pypi-<PYPI_TOKEN>

You can also set UV_PUBLISH_TOKEN in your environment instead of passing --token.

License

MIT — see LICENSE.