🚧 Under Construction - There might be incompatible interface changes between minor versions of version zero!

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

On this note, you probably also want to switch to the specific documentation for the version you’re using (somewhere at the lower left corner of this page).

Top-Level Definitions


Sets the global font ratio.


ratio (Union[float, term_image.FontRatio]) –

Can be one of the following values.

  • TypeError – An argument is of an inappropriate type.

  • ValueError – An argument is of an appropriate type but has an unexpected/invalid value.

  • term_image.exceptions.TermImageError – Auto font ratio is not supported in the active terminal or on the current platform.

This value is taken into consideration when setting image sizes for text-based render styles, in order to preserve the aspect ratio of images drawn to the terminal.


Changing the font ratio does not automatically affect any image that already has it’s size set. For a change in font ratio to have any effect, the image’s size has to be set again.


See Auto Font Ratio for details about the auto modes.


Returns the global font ratio.

See set_font_ratio().

class term_image.FontRatio(value)

Bases: enum.Enum

Constants for auto font ratio modes

class term_image.TermImageWarning

Bases: UserWarning

Package-specific warning category

Render Styles

A render style is a specific implementation of representing or drawing images in a terminal emulator and each is implemented as a class.

All render styles are designed to share a common interface (with some styles having extensions), making the usage of one class directly compatibile with another, except when using style-specific features.

Hence, the covenience functions AutoImage, from_file() and from_url() provide a means of render-style-independent usage of the library.
These functions automatically detect the best render style supported by the active terminal.

There a two categories of render styles:

Text-based Render Styles

Represent images using ASCII or Unicode symbols, and in some cases, in conjunction with ANSI colour escape codes.

Classes for render styles in this category are subclasses of TextImage. These include:

Graphics-based Render Styles

Represent images with actual pixels, using terminal graphics protocols.

Classes for render styles in this category are subclasses of GraphicsImage. These include:

Auto Font Ratio

When using auto font ratio (in either mode), it’s important to note that some (not all) terminal emulators (e.g VTE-based ones) might have to be queried. See Terminal Queries.

If the program will never expect any useful input, particularly while an image’s size is being set or when an image with unset size is being rendered, then using FULL_AUTO mode is OK.

Otherwise i.e if the program will be expecting input, use AUTO mode and use utils.read_tty() to read all currently unread input just before calling set_font_ratio().

Image Format Specification

[h_align] [width] [ . [v_align] [height] ] [ # [threshold | bgcolor] ] [ + {style} ]


  • The spaces are only for clarity and not included in the syntax.

  • Fields within [ ] are optional.

  • Fields within { } are required, though subject to any enclosing [ ].

  • | implies mutual exclusivity.

  • If the . is present, then at least one of v_align and height must be present.

  • width and height are in units of columns and lines repectively.

  • If the padding width or padding height is less than or equal to the image’s rendered width or rendered height respectively, the padding has no effect.

  • h_align: This can be one of:

    • < → left

    • | → center

    • > → right

    • Default → center

  • width: padding width

  • v_align: This can be one of:

    • ^ → top

    • - → middle

    • _ → bottom

    • Default → middle

  • height: padding height

  • #: Transparency setting:

    • Default: transparency is enabled with the default alpha threshold.

    • threshold: alpha threshold e.g .0, .325043, .99999.

      • The value must be in the range 0.0 <= threshold < 1.0.

      • Applies to only text-based render styles e.g. BlockImage.

    • bgcolor: Color to replace transparent background with. Can be:

      • # -> The terminal’s default background color (or black, if undetermined) is used.

      • A hex color e.g ffffff, 7faa52.

    • If neither threshold nor bgcolor is present, but # is present, transparency is disabled (alpha channel is removed).

  • style: Style-specific format specifier.

    See each render style in Image Classes for its own specification, if it defines.

    style can be broken down into [parent] [current], where current is the spec defined by a class and parent is the spec defined by a parent of that class. parent can in turn be recursively broken down as such.

See Formatted rendering for examples.