Skip to main content

Display images in the terminal

Project description


Display Images in the terminal

Documentation Status




  • Operating System: Unix / Linux / Mac OS X / Windows (limited support, see the FAQs)

  • Python >= 3.7

  • A terminal emulator with any of the following:

    Plans to support a wider variety of terminal emulators are in motion (see here).


The latest stable version can be installed from PyPI using pip:

pip install term-image

The development version can be installed thus:

NOTE: it's recommended to install in an isolated virtual environment which can be created by any means.

Clone this repository from within a terminal

git clone

then navigate into the local repository

cd term-image

and run

pip install .

Supported Terminal Emulators

See here for a list of tested terminal emulators.

If you've tested term-image on any other terminal emulator that meets the requirements for any of the render styles, please mention the name (and version) in a new thread under this discussion.

Also, if you have any issue with terminal support, you may report or check information about it in the discussion linked above.


Library features

  • Multiple image formats (basically all formats supported by
  • Multiple image source types: PIL image instance, local file, URL
    • Exposes various features of the protocols
  • Multiple image render styles (with automatic support detection)
  • Support for multiple terminal graphics protocols: Kitty, iTerm2
  • Transparency support (with multiple options)
  • Animated image support (including transparent ones)
    • Multiple formats: GIF, WEBP, APNG (and possibly more)
    • Fully controllable iteration over rendered frames of animated images
    • Image animation with multiple parameters
  • Terminal size awareness
  • Automatic and manual image sizing
  • Horizontal and vertical alignment
  • Automatic and manual font ratio adjustment (to preserve image aspect ratio)
  • Well-documented
  • and more... :grin:

CLI/TUI features

  • Almost everything the library supports
  • Individual/Multiple image display [CLI]
  • Browse multiple images and directories (recursively) [TUI]
  • Adjustable image grids [TUI]
  • Context-based controls [TUI]
  • Customizable controls and configuration options
  • Smooth and performant experience
  • and more... :grin:

How does this project compare with similar ones?

As far as I know, the only aspect of this project that any other currently existing project can be compared with is the CLI.

I prefer to leave comparisons to the users.


Check out the gallery.

Click to expand

TUI Demo Video

*The video was recorded at normal speed and not sped up.

CLI/TUI Quick Start

Click to expand

With a local image file

term-image path/to/image.png

With an image URL


With a directory, recursively (not currently supported on Windows)

term-image -r path/to/dir/

If the image is animated (GIF, WEBP), the animation is infinitely looped by default but can be stopped with Ctrl-C.

By default, if multiple sources or at least one directory is given, the TUI (Text-based/Terminal User Interface) is launched to navigate through the images (and/or directories).

NOTE: python -m term_image can be used as an alternative to the term-image command (take note of the underscore VS hyphen).

Library Quick Start

Click to expand

Creating an instance

from term_image.image import from_file

image = from_file("path/to/image.png")

You can also use a URL if you don't have the file stored locally

from term_image.image import from_url

image = from_url("")

The library can also be used with PIL images

from PIL import Image
from term_image.image import AutoImage

img ="path/to/image.png")
image = AutoImage(img)

Drawing/Displaying an image to/in the terminal

There are two ways to draw an image to the terminal.

1. The draw() method


2. Using print() with a rendered image

print(image)  # without formatting


print(f"{image:>200.^100#ffffff}")  # with formatting

For animated images, only the first method can animate the output, the second only outputs the current frame.


:construction: Under Construction - There might be incompatible changes between minor versions of version zero!

If you want to use term-image in a project while it's still on version zero, ensure you pin the dependency version to a specific minor version e.g >=0.4,<0.5.


See the tutorial for a more detailed introduction and the reference for full descriptions and details of the available features.

CLI (Command-Line Interface)

Run term-image --help to see the full usage info and list of options.

TUI (Text-based/Terminal User Interface)

The controls are context-based and displayed at the bottom of the terminal window. Pressing the F1 key (in most contexts) brings up a help menu describing the available controls (called actions) in that context.

The TUI can be configured by modifying the config file ~/.term_image/config.json. See the Configuration section of the docs.

Here is a config file with Vim-style key-bindings (majorly navigation). Remember to rename the file to config.json.


If you've found any bug or want to suggest a new feature, please open a new issue with proper description, after browsing/searching through the existing issues and making sure you won't create a duplicate.

For code contributions, please read through the guidelines.

Also, check out the Planned Features section below. If you wish to work on any of the listed tasks, please click on the linked issue or go through the issues tab and join in on an ongoing discussion about the task or create a new issue if one hasn't been created yet, so that the implementation can be discussed.

Hint: You can filter issues by label or simply search using the task's name or description.

For anything other than the above (such as questions or anything that would fit under the term "discussion"), please open a new discussion instead.

Thanks! :heart:

Planned Features

Check here for the library and here for the image viewer.

Known Issues

Check here for the library and here for the image viewer.


See the FAQs section of the docs.


The following projects have been (and are still) crucial to the development of this project:


Your donation will go a long way in aiding the progress and development of this project.

USDT Address: TKP6d3hLcs7i5R18WRFxLe3zsPQcCBS1Ro
Network: TRC20

I'm sincerly sorry for any inconviences that may result from the means of donation.

Please bare with me, as usual means of accepting donations are not available in the region of the world where I reside.

Thank you! :heart:

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

term-image-0.4.1.tar.gz (96.3 kB view hashes)

Uploaded Source

Built Distribution

term_image-0.4.1-py3-none-any.whl (106.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page