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:
CLI modeIn this mode, images are directly printed to standard output.This mode is used whenever there is only a single image source or when the
--clioption is specified.
TUI modeIn this mode, a Terminal/Text-based User Interface is launched, within which images and directories can be browsed and viewed in different ways.This mode is used whenever there are multiple image sources or at least one directory source, or when the
--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.
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.logbut 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
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.
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.
6(INVALID_ARG): Exited due to an invalid command-line argument value.
The TUI is not supported on Windows
Drawing of images and animations doesn’t work completely well with
powershell(tested in Windows Terminal). See Known Issues for details.
In the viewer’s CLI mode, use the
--h-allowoption to specify a horizontal allowance.
Open in external viewer
Pattern-based file and directory exclusion
Minimum and maximum file size
Optionally skipping symlinks
Distinguished color for symlinked entries in the list view
Full grid view
Grid cells for directory entries
Interactive CLI mode
Find in iist view
Filter in list and grid views
Alpha backaground adjustment per image
Frame duration adjustment per animated image
Parent directory path
Overlay support for