🚧 Under Construction - There might be incompatible changes (particularly in the CLI options and configuration) between minor versions of version zero!
If you want to use the viewer in a project while it’s still on version zero,
ensure you pin the dependency to a specific minor version e.g
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).
The package comes with a standalone in-terminal image viewer based on the library.
term-imagecommand (only works if the Python scripts directory is on
python -m term_image.
The viewer accepts the following kinds of sources:
An image file on a local filesystem.
A directory on a local filesystem.
An Image URL.
Any other thing given as a source is simply reported as invalid.
The viewer can be used in two modes:
In this mode, images are directly printed to standard output. It is used when:
output is not a terminal
there is only a single image source
--clioption is specified
In this mode, a Terminal/Text-based User Interface is launched, within which images and directories can be browsed and viewed in different ways. It is used when:
there is at least one non-empty directory source
there are multiple image sources
--tuioption is specified
--helpoption to see the usage info and help text.
Note that some options are only applicable to a specific mode. If used with the other mode, they’re simply ignored.
[N](where N is a number) behind their description, it indicates that the option has a footnote attached.
See Render Styles.
By default, the best style supported by the active terminal is automatically detected.
A particular render style can be specified using the
style config option
-S | --style command-line option.
1(FAILURE, see the description below).
--force-style command-line option can be used to bypass style support checks and force the usage of any style whether it’s supported or not.
The font ratio 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.
font ratioOR either of the command-line options
-F | --font-ratioand
term-imagetries to determine the value from the active terminal which works on most mordern terminal emulators (currently supported on UNIX-like platforms only).
term-imageis unable to determine this value automatically, it falls back to
0.5, which is a reasonable value in most cases.
If using auto font ratio and the active terminal is not the controlling terminal of the
term-image process (e.g output is redirected to another terminal), ensure no process that might read input (e.g a shell) is currently running in the active terminal, as such a process might interfere with determining the font ratio on some terminal emulators (e.g VTE-based ones).
For instance, the
sleep command can be executed if a shell is currently running in the active terminal.
Standard output/error stream: This is used while the TUI is not launched.
TUI notification bar: This is used while the TUI is launched.
Notifications sent to the TUI’s notification bar automatically disappear after 5 seconds.
Logs are more detailed event reports meant for troubleshooting and debugging purporses.
Logs are written to a file on a local filesystem. The default log file is
~/.term_image/term_image.log but a different file can be specified:
for all sessions, using the log file config option
per session, using the
A log entry has the following format:
(<pid>) (<date> <time>) <process>: <thread>: [<level>] <module>: <function>: <message>
pid: The process ID of the term-image session.
date and time: Current system date and time in the format
%Y-%m-%d %H:%M:%S,<ms>, where
<ms>is in milliseconds.
process and thread: The names of the python process and thread that produced the log record.
Only present when the logging level is set to
level: The level of the log entry, this indicates it’s importance.
module: The package sub-module from which it originated.
function: The function from which it originated.
Only present when running on Python 3.8+ and logging level is set to
message: The actual report describing the event that occured.
Certain logs and some extra info are only provided when logging level is set to
Log files are appended to, so it’s safe use the same file for multiple sessions.
Log files are rotated upon reaching a size of 1MiB.
Only the current and immediate previous log file are kept.
The Process ID of the
term-imageinstance preceeds every log entry, so this can be used to distinguish and track logs from different sessions running simultaneously while using the same log file.
term-image returns the following exit codes with the specified meanings:
0(SUCESS): Exited normally and successfully.
1(FAILURE): Exited due to an unhandled exception or a non-specific error.
2(INVALID_ARG): Exited due to an invalid command-line argument value or option combination.
3(INTERRUPTED): The program recieved an interrupt signal i.e
4(CONFIG_ERROR): Exited due to an irremediable error while loading the user config.
5(NO_VALID_SOURCE): Exited due to lack of any valid source.
The TUI is not supported on Windows
Drawing of images and animations doesn’t work completely well with Python for windows (tested in Windows Terminal and MinTTY). See here for details.
In the viewer’s CLI mode, use the
--h-allowoption to specify a horizontal allowance.
Some animations with the kitty render style within the Kitty terminal emulator might be glitchy at the moment. See here for details.
In no particular order:
Open image in external viewer
Pattern-based file and directory exclusion
Minimum and maximum file size
Optionally following/skipping symlinks
Distinguished color for symlinked entries in the list view
Full grid view [TUI]
Grid cells for directory entries [TUI]
CLI grid view
Interactive CLI mode
Search in iist view
Filter in list and grid views
Alpha backaground adjustment per image
Frame duration adjustment per animated image
Parent directory path
Also check the library’s Planned Features since the viewer is based on it.