ASCII Magic

2.7.4 · active · verified Sat Apr 11

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.

Warnings

breaking Version 2.0 introduced a complete rewrite of the library, transitioning to a full object-oriented programming (OOP) model. Code written for 1.x versions is no longer compatible with 2.x and above.
Fix: Rewrite existing code to use the `AsciiArt` class and its methods (e.g., `AsciiArt.from_image()`, `my_art.to_terminal()`).
deprecated Support for DALL-E, Stable Diffusion, and Craiyon APIs was removed in v2.6 and v2.4 due to API availability changes. Functions like `from_dalle()` and `from_stable_diffusion()` are no longer available.
Fix: Migrate to newer integrated AI features like `from_gemini()` (v2.6) or `from_swarmui()` (v2.7), or handle image generation externally and pass a Pillow image object using `AsciiArt.from_pillow_image()`.
gotcha On some Windows terminals, colors might not display correctly even if enabled. This is often due to the terminal's compatibility with ANSI escape codes.
Fix: Install `colorama` (`pip install colorama`) and call `colorama.init()` before printing ASCII art to the terminal: `import colorama; colorama.init(); my_art.to_terminal()`.
gotcha When using `AsciiArt.from_url()`, network or server issues can cause `urllib.error.URLError` (or a generic `OSError`) if the image cannot be fetched.
Fix: Wrap calls to `from_url()` in a `try-except` block to gracefully handle potential `OSError` or `urllib.error.URLError` exceptions, informing the user about the issue.

Install

pip install ascii-magic Install with pip

Imports

AsciiArt
```
from ascii_magic import AsciiArt
```
Since v2.0, the library was completely rewritten to be object-oriented. All core functionality is accessed via the `AsciiArt` class methods.

Quickstart

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)

view raw JSON →