The library consists of the following:

Top-Level Functions


Return the set libray-wide font ratio

Return type



Set the library-wide font ratio


ratio (float) – The aspect ratio of your terminal’s font i.e width / height of a single character cell.

Return type


This value is taken into consideration when rendering images in order for images drawn to the terminal to have a proper perceived scale.

If you can’t determine this value from your terminal’s configuration, you might have to try different values till you get a good fit. Normally, this value should be between 0 and 1, but not too close to either.

Image Format Specification

[h_align] [width] [ . [v_align] [height] ] [ # [threshold | bgcolor] ]


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

  • Fields within [ ] are optional.

  • | implies mutual exclusivity.

  • 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

    • absent → center

  • width: Integer padding width (default: terminal width minus horizontal allowance)

  • v_align: This can be one of:

    • ^ → top

    • - → middle

    • _ → bottom

    • absent → middle

  • height: Integer padding height (default: terminal height minus vertical allowance)

  • #: Transparency setting:

    • If absent, transparency is enabled.

    • threshold: Alpha ratio above which pixels are taken as opaque e.g .0, .325043, .99999. The value must be in the range 0.0 <= threshold < 1.0.

    • bgcolor: Hex color with which transparent background should be replaced e.g ffffff, 7faa52.

    • If neither threshold nor bgcolor is present, but # is present, transparency is disabled i.e the image has a black background.

See Formatted rendering for examples.