ASCII Magic is a Python package (v2.7.4) that converts images into ASCII art for terminals and HTML. It provides functionalities to generate ASCII art from local image files, URLs, or Pillow image objects. The library is actively maintained, with several minor releases in late 2025 and early 2026 that introduced new features and addressed compatibility issues.
Install & Compatibility
Where this runs
tested against v2.7.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.194s · 38.2MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 2.2s · import 0.176s · 39MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Since v2.0, the library was completely rewritten to be object-oriented. All core functionality is accessed via the `AsciiArt` class methods.
from ascii_magic import AsciiArt
This quickstart demonstrates how to load an image from a local file and display its ASCII art representation in the terminal. It also shows how to export the ASCII art to an HTML file. Replace `dummy_image.png` with your desired image file.
import os
from ascii_magic import AsciiArt
# Create a dummy image file for demonstration
dummy_image_path = "dummy_image.png"
with open(dummy_image_path, "wb") as f:
# A minimal (invalid) PNG header to simulate a file
f.write(b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\x0cIDATx\xda\xed\xc1\x01\x01\x00\x00\x00\xc2\xa0\xf7Om\x00\x00\x00\x00IEND\xaeB`\x82')
try:
# Create AsciiArt object from an image file
# Replace 'dummy_image.png' with your actual image path or a URL (AsciiArt.from_url)
my_art = AsciiArt.from_image(dummy_image_path)
# Print the ASCII art to the terminal
my_art.to_terminal(columns=80)
# Example of saving to an HTML file
my_art.to_html_file('output.html', columns=120, full_color=True)
print("ASCII art saved to output.html")
except FileNotFoundError:
print(f"Error: Image file '{dummy_image_path}' not found. Please provide a valid image path.")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# Clean up the dummy image file
if os.path.exists(dummy_image_path):
os.remove(dummy_image_path)
ascii_magic --version
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.