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.95 runs
installs and imports cleanly · install 0.0s · import 0.196s · 38.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.2s · import 0.168s · 39MB
36MB installed
● package 36MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AsciiArt
✓ from ascii_magic import AsciiArt
✗ import ascii_magic; ascii_magic.from_image(...)
Since v2.0, the library was completely rewritten to be object-oriented. All core functionality is accessed via the `AsciiArt` class methods.
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
Debug
Known issues
breakingVersion 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.fixRewrite existing code to use the `AsciiArt` class and its methods (e.g., `AsciiArt.from_image()`, `my_art.to_terminal()`).
affects: >=2.0.0
deprecatedSupport 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.fixMigrate 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()`.
affects: >=2.4.0, >=2.6.0
gotchaOn some Windows terminals, colors might not display correctly even if enabled. This is often due to the terminal's compatibility with ANSI escape codes.fixInstall `colorama` (`pip install colorama`) and call `colorama.init()` before printing ASCII art to the terminal: `import colorama; colorama.init(); my_art.to_terminal()`.
affects: All versions
gotchaWhen using `AsciiArt.from_url()`, network or server issues can cause `urllib.error.URLError` (or a generic `OSError`) if the image cannot be fetched.fixWrap 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'ascii_magic'
The 'ascii_magic' package is not installed in the Python environment.
fixInstall the package using pip: 'pip install ascii_magic'.
ImportError: cannot import name 'AsciiArt' from 'ascii_magic'
The 'AsciiArt' class is not available in the installed version of 'ascii_magic'.
fixEnsure you have 'ascii_magic' version 2.0 or later installed, as 'AsciiArt' was introduced in version 2.0.
TypeError: from_image() missing 1 required positional argument: 'path'
The 'from_image()' function requires a 'path' argument specifying the image file location.
fixProvide the image file path when calling 'from_image()', e.g., 'ascii_magic.from_image('path/to/image.jpg')'. OSError: The clipboard does not contain an image
Attempting to create an 'AsciiArt' object from the clipboard when it does not contain an image.
fixEnsure the clipboard contains an image before calling 'AsciiArt.from_clipboard()'.
urllib.error.URLError: <urlopen error [Errno 11001] getaddrinfo failed>
The URL provided to 'from_url()' is invalid or the network is unreachable.
fixVerify the URL is correct and ensure you have an active internet connection before calling 'from_url()'.
Upgrade
Version history
2.7.5latest on PyPI · released Apr 12, 2026
Audit
Dependencies
PillowrequiredRequired for image processing and handling various image formats.
coloramaoptionalRecommended for enabling color output in older Windows terminals if colors do not display correctly. No longer a direct dependency since v2.4 for modern Windows.