Skip to main content

A utility for converting images to text art.

Project description


A utility for converting images to text art.
PyPI - Status pypi package GitHub

Installation    |    Documentation    |    Examples    |    Contributing


Run the following command:

pip install picharsso

This will:

  • download and install the picharsso Python package (along with its dependencies).
  • create an executable, picharsso, for the CLI (command line interface).


To verify that Picharsso is installed, run:

python -c "import picharsso"


Picharsso ships with a CLI that provides some basic functionality from the terminal.


Run the following command to display a helpful message:

picharsso -h
Usage: picharsso [options] <command> [args]

  A utility for converting images to text art.

  -h, --help  Show this message and exit.

  draw  Generate text art from an image.
  info  Displays package information.

Consider the following image:

Apple logo

Apple Computer [Rob Janoff, 1977]

To convert an image to text art, run:

picharsso draw -c -H 32 <path/to/image> gradient

Here's what it should look like:

Apple logo in text (gradient style)


Argument Effect
-c Apply image colors to the output text.
-H 32 Sets the number of lines of the output text to 32.
gradient Use the gradient style.

Don't forget to replace <path/to/image>.

Refer to the CLI documentation to learn about the various commands and arguments.


The example from the previous section can be implemented in just a few lines of Python:

from PIL import Image
from picharsso import new_drawer

if __name__ == "__main__":
    # Open image
    image ="<path/to/image>")

    # Define drawer
    drawer = new_drawer("braille", height=32, colorize=True)

    # Print drawer output

Here's what it should look like:

Apple logo in text (Braille style)


Refer to the Styles documentation for an in-depth guide to the image processing behind Picharsso.

Now consider this animated GIF:

Nyan Cat

Nyan Cat

With some more lines of code, you can animate GIFs in text!

import time

from PIL import Image
from picharsso import new_drawer
from picharsso.utils import clear_screen, terminal_size

if __name__ == "__main__":
    # Open image
    image ="<path/to/image>")

    # Get terminal height
    height, _ = terminal_size()

    # Define drawer
    drawer = new_drawer("braille", height=height, colorize=True, threshold=0)

    # Iterate over frames
    texts = []
    for frame_id in range(image.n_frames):
        # Select frame

        # Save output for frame

    # Iterate over saved outputs in a circular manner
    num_frames = len(texts)
    counter = 0
    while True:
        # Refresh

        # Print output

        # Set a delay between frames
        time.sleep(1 / num_frames)

        # Circular increment
        counter = (counter + 1) % num_frames

Here's what it should look like:

Nyan Cat in text (Braille style)

Refer to the API documentation to learn about the various classes and functions.


Check out some more examples.

You can use an image directly from the web too!


Do you have a feature request, bug report, or patch? Great! Check out the contributing guidelines!


Copyright (c) 2019 Kelvin DeCosta. Released under the MIT License. See LICENSE for details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

picharsso-2.0.1.tar.gz (13.0 kB view hashes)

Uploaded source

Built Distribution

picharsso-2.0.1-py3-none-any.whl (19.1 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page