Simple Terminal Menu

Overview

simple-term-menu creates simple menus for interactive command line programs. It can be used to offer a choice of different options to the user. Menu entries can be selected with the arrow, j/k, or emacs (C-n/C-p) keys. The module uses the terminfo database to detect terminal features automatically and disables styles that are not available. Currently, Linux and macOS are supported.

Breaking changes

From version 0.x to 1.x

If you update from version 0.x to 1.x, please consider these breaking changes:

• The TerminalMenu constructor now only takes keyword-only arguments (except for the first parameter which contains the menu entries). This makes it easier to add new parameters in future releases and allows to keep a well-arranged parameter list.

• The command line interface was revised. It now uses - instead of _ to separate words consistently and rearranges short options. Only the most important short options were kept to save free letters for future releases.

From version 1.1 to 1.2

• The multi_select_key parameter is now named multi_select_keys and takes an iterable of keys and by default space andtab are now used as multi-select keys. This allows to toggle selected items in search mode.

• The shortcut_parentheses_highlight_style parameter is renamed to shortcut_brackets_highlight_style to be more consistent with the new multi_select_cursor_brackets_style parameter.

Installation

simple-term-menu is available on PyPI for Python 3.5+ and can be installed with pip:

python3 -m pip install simple-term-menu

If you use Arch Linux or one of its derivatives, you can also install simple-term-menu from the AUR:

yay -S python-simple-term-menu

You also find self-contained executables for 64-bit Linux distributions and macOS High Sierra and newer on the releases page. They are created with PyInstaller and only require glibc >= 2.17 on Linux (should be fine on any recent Linux system).

Usage

Create a menu with the default style

Create an instance of the class TerminalMenu and pass the menu entries as a list of strings to the constructor. Call the show method to output the menu and wait for keyboard input:

#!/usr/bin/env python3

from simple_term_menu import TerminalMenu

def main():
    options = ["entry 1", "entry 2", "entry 3"]
    terminal_menu = TerminalMenu(options)
    menu_entry_index = terminal_menu.show()
    print(f"You have selected {options[menu_entry_index]}!")

if __name__ == "__main__":
    main()

You will get an output like:

You can now select a menu entry with the arrow keys or j/k (vim motions) and accept your choice by hitting enter or cancel the menu with escape, q or <Ctrl>-C. show returns the selected menu entry index or None if the menu was canceled.

You can pass an optional title to the TerminalMenu constructor which will be placed above the menu. title can be a simple string, a multiline string (with \n newlines) or a list of strings. The same applies to the status_bar parameter, which places a status bar below the menu. Moreover, you can use a callable as status_bar parameter which takes the currently selected entry and returns a status bar string.

Styling

You can pass styling arguments to the TerminalMenu constructor. Each style is a tuple of keyword strings. Currently the following keywords are accepted:

• bg_black
• bg_blue
• bg_cyan
• bg_gray
• bg_green
• bg_purple
• bg_red
• bg_yellow
• fg_black
• fg_blue

File truncated at 100 lines see the full file