whiptail

Terminal dialog boxes for shell scripts

TLDR

Display a simple message box

$ whiptail --title "[title]" --msgbox "[message]" [height] [width]

Display a yes/no choice

$ whiptail --title "[title]" --yesno "[message]" [height] [width]

Customize yes/no button text

$ whiptail --title "[title]" --yes-button "[text]" --no-button "[text]" --yesno "[message]" [height] [width]

Display a text input box

$ result=$(whiptail --title "[title]" --inputbox "[message]" [height] [width] [default] 3>&1 1>&2 2>&3)

Display a password input box

$ result=$(whiptail --title "[title]" --passwordbox "[message]" [height] [width] 3>&1 1>&2 2>&3)

Display a menu with choices

$ result=$(whiptail --title "[title]" --menu "[message]" [height] [width] [menu_height] "val1" "text1" "val2" "text2" 3>&1 1>&2 2>&3)

Display a checklist for multiple selections

$ result=$(whiptail --title "[title]" --checklist "[message]" [height] [width] [list_height] "opt1" "text1" ON "opt2" "text2" OFF 3>&1 1>&2 2>&3)

Display a progress bar (gauge)

$ echo [50] | whiptail --title "[title]" --gauge "[message]" [height] [width] [0]

SYNOPSIS

whiptail [--title title] [--backtitle backtitle] box-type [box-options] height width

whiptail displays text-based dialog boxes from shell scripts, providing a user-friendly interface for input and selection. It creates ncurses-based dialogs that work in terminal environments, supporting various dialog types including messages, input boxes, menus, and progress bars.Output from input dialogs goes to stderr, requiring file descriptor redirection (3>&1 1>&2 2>&3) to capture in shell variables. Exit codes indicate user choices (0 for OK/Yes, 1 for Cancel/No).

PARAMETERS

--title title

Dialog title

--backtitle text

Background title

--msgbox text height width

Display message with OK button

--yesno text height width

Display yes/no dialog

--inputbox text height width [init]

Text input dialog

--passwordbox text height width

Password input (hidden text)

--menu text height width menu-height [tag item]...

Selection menu

--checklist text height width list-height [tag item status]...

Multiple choice checklist

--radiolist text height width list-height [tag item status]...

Radio button list

--gauge text height width percent

Progress bar

--yes-button text

Custom yes button label

--no-button text

Custom no button label

--ok-button text

Custom OK button label

--cancel-button text

Custom cancel button label

--defaultno

Default to No in yes/no dialogs

--nocancel

Suppress the Cancel button

--separate-output

Output checklist results one per line

--scrolltext

Force display of a vertical scrollbar

--topleft

Place dialog in the top-left corner

--clear

Clear the screen on exit

--fullbuttons

Use full-width buttons instead of compact

--output-fd FD

Direct output to given file descriptor instead of stderr

--textbox file height width

Display contents of a file in a scrollable box

--infobox text height width

Display message without waiting for input

CAVEATS

Dialog dimensions must be specified in characters and should fit the terminal. Results go to stderr, requiring fd redirection for capture. A lightweight alternative to dialog with fewer features but smaller dependencies.

HISTORY

Created as a lightweight, newt-based reimplementation of the dialog utility. Part of the newt library developed by Red Hat. Commonly used in Debian installer and system configuration scripts due to its small footprint.