Skip to main content

Display images in the terminal

Project description


Display Images in the terminal




  • Operating System: Unix / Linux / MacOS X / Windows (partial, more info in the FAQs)
  • Python >= 3.6
  • A Terminal emulator with full Unicode support and ANSI 24-bit color support
    • Plans are in place to [partially] support terminals not meeting this requirement (see here).


The package can be installed from PyPI using pip:

pip install term-image


Clone this repository using any method, then navigate into the project directory in a terminal and run:

pip install .

Supported Terminal Emulators

See here for a list of tested terminal emulators.

If you've tested term-img on any other terminal emulator that meets all requirements, please mention the name in a new thread under this discussion. Also, if you're having an issue with terminal support, also report or view information about it in the discussion linked above.


Library features

  • Multiple image format support
    • Basically supports all formats supported by
  • Multiple image sources (PIL image, local file, URL)
  • Transparency support (with multiple options)
  • Animated image support (including transparent ones)
  • Terminal size awareness
  • Variable image size
  • Automatic image sizing; best fit within the terminal window or a given size
  • Variable image scale
  • Horizontal and vertical alignment/padding
  • Font-ratio adjustment
  • Frame duration (animation speed) control
  • ... more coming soon :grin:

CLI/TUI features

  • Basically everything the library supports
  • Individual image display
  • Multiple images / Directory / Recursive browsing
  • Image grid [TUI]
  • Context-based controls [TUI]
  • Dynamic controls (context actions are disabled and enabled dynamically) [TUI]
  • Customizable controls and configuration options
  • Automatic adjustment upon terminal resize [TUI]
  • Image deletion [TUI]
  • Notification system
  • Detailed logging system
  • ... more coming soon :grin:

CLI/TUI Quick Start

From a local image file

term-img path/to/image.png

From a URL


If the image is animated (GIF, WEBP), the animation is infinitely looped 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.

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

Library Quick Start

Creating an instance

from term_img.image import TermImage

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

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

from term_img.image import TermImage

image = TermImage.from_url("")

The library can also be used with PIL images

from PIL import Image
from term_img.image import TermImage

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

Rendering an image

Rendering an image, in this context, is simply the process of converting it into text (a string). There are two ways to render an image:

1. Unformatted


Renders the image without padding/alignment and with transparency enabled.

2. Formatted

format(image, "|200.^100#ffffff")

Renders the image with:

  • center horizontal alignment
  • a padding width of 200 columns
  • top vertical alignment
  • a padding height of 70 lines
  • transparent background replaced with a white (#ffffff) background

Renders the image with:

  • right horizontal alignment
  • automatic padding width (the current terminal width minus horizontal allowance)
  • bottom vertical alignment
  • automatic padding height (the current terminal height minus vertical allowance)
  • transparent background with 0.5 alpha threshold

Renders the image with:

  • center horizontal alignment (default)
  • no horizontal padding, since 1 must be less than or equal to the image width
  • middle vertical alignment (default)
  • no vertical padding, since 1 is less than or equal to the image height
  • transparency disabled (black background)

Drawing/Displaying an image to/in the terminal

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

1. The draw() method


NOTE: TermImage.draw() method has various parameters for alignment/padding, transparency and animation control.

2. Using print() with an image render output (i.e printing the rendered string)

print(image)  # Uses str()


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

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

NOTE: All the above examples use automatic sizing and default scale.


CLI (Command-Line Interface)

Run term-img --help to see full usage info.

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 controls can be configured by modifying the config file ~/.term_img/config.json. See the Configuration section. Here is a config file with Vim-style key-bindings (majorly navigation). Remember to rename the file to config.json.


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

NOTE: The project is currently at a stage where the public API might change without warning but significant changes will always be specified in the changelog.


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 make sure you read through the guidelines.

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

Hint: You can filter discussions by Category or 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:


  • Performance improvements


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


See the FAQs section of the docs.


This project started as a fork of img by @pranavbaburaj but has since grown into something almost entirely different.

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.1.1.tar.gz (44.0 kB view hashes)

Uploaded Source

Built Distribution

term_image-0.1.1-py3-none-any.whl (48.6 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