whiptail

whiptail은 shell script에서 message, 질문, menu, checklist, progress gauge를 표시하는 TUI utility다. ncurses 기반 dialog와 달리 newt/S-Lang 계열을 사용하며 widget 범위가 더 작다.

• 설치 프로그램, rescue 환경, 간단한 관리 script에서 대화형 입력을 받을 때 사용한다.
• 선택값은 기본적으로 standard error로 출력한다.
• dialog 호환 interface를 일부 제공하지만 option, widget, 표시, output 동작이 완전히 같지는 않다.

sudo apt update
sudo apt install whiptail

Fedora의 newt package가 whiptail executable을 제공한다.

sudo dnf install newt

Homebrew는 upstream newt distribution을 formula로 제공한다.

brew install newt

설치 후 현재 formula가 whiptail executable을 포함하는지 verification command로 확인한다.

2026-08-10 기준 upstream과 Microsoft winget에서 공식 Windows용 whiptail package 설치 방법은 확인되지 않는다. Windows에서는 WSL의 Linux 배포판 package를 사용하는 방법을 우선 검토한다.

command -v whiptail
whiptail --version

이 저장소의 base environment에서 확인한 version은 whiptail (newt): 0.52.20이다.

whiptail --title "Message" --msgbox "Hello, World" 10 40

• whiptail [OPTIONS] WIDGET WIDGET_ARGUMENTS

• –msgbox TEXT HEIGHT WIDTH: OK message box를 표시한다.
• –yesno TEXT HEIGHT WIDTH: Yes/No 질문을 표시한다.
• –infobox TEXT HEIGHT WIDTH: 대기하지 않고 정보를 표시한다.
• –inputbox TEXT HEIGHT WIDTH [INIT]: 문자열을 입력받는다.
• –passwordbox TEXT HEIGHT WIDTH [INIT]: 입력 문자를 숨겨 문자열을 받는다.
• –textbox FILE HEIGHT WIDTH: text file을 표시한다.
• –menu TEXT HEIGHT WIDTH LIST_HEIGHT [TAG ITEM]…: 항목 하나를 선택한다.
• –checklist TEXT HEIGHT WIDTH LIST_HEIGHT [TAG ITEM STATUS]…: 여러 항목을 선택한다.
• –radiolist TEXT HEIGHT WIDTH LIST_HEIGHT [TAG ITEM STATUS]…: 단일 선택 목록을 표시한다.
• –gauge TEXT HEIGHT WIDTH PERCENT: standard input으로 받은 진행률을 표시한다.

• –clear: 종료할 때 화면을 지운다.
• –defaultno: No button을 기본값으로 둔다.
• –default-item STRING: menu의 초기 항목을 지정한다.
• –fullbuttons, –fb: compact button 대신 full button을 사용한다.
• –nocancel: Cancel button을 숨긴다.
• –yes-button TEXT: Yes button text를 바꾼다.
• –no-button TEXT: No button text를 바꾼다.
• –ok-button TEXT: OK button text를 바꾼다.
• –cancel-button TEXT: Cancel button text를 바꾼다.
• –noitem: item 설명을 표시하지 않는다.
• –notags: tag를 표시하지 않는다.
• –separate-output: checklist 결과를 인용 없이 한 줄에 하나씩 출력한다.
• –output-fd FD: 결과를 지정한 file descriptor로 보낸다.
• –title TITLE: dialog box 제목을 표시한다.
• –backtitle BACKTITLE: 화면 상단 배경 제목을 표시한다.
• –scrolltext: vertical scrollbar를 강제로 표시한다.
• –topleft: window를 왼쪽 위에 배치한다.
• –help, -h: help를 출력한다.
• –version, -v: version을 출력한다.

255만으로 사용자 Esc와 내부 error를 구분할 수 없으므로 필요하면 호출 전 terminal 조건과 error message를 함께 기록한다.

if whiptail --defaultno --yesno "파일을 삭제하시겠습니까?" 10 40; then
    printf '%s\n' "사용자가 삭제를 승인했습니다."
else
    printf '%s\n' "취소했습니다."
fi

whiptail은 결과를 기본적으로 standard error에 쓴다. 기존 shell script에서 흔히 사용하는 FD swap을 적용한다.

action=$(whiptail --menu "시스템 설정 도구" 15 40 4 \
    "1" "네트워크 설정" \
    "2" "사용자 추가" \
    "3" "서비스 재시작" 3>&1 1>&2 2>&3)
status=$?
 
if [ "$status" -eq 0 ]; then
    case "$action" in
        "1") /path/to/network-setup.sh ;;
        "2") /path/to/user-add.sh ;;
        "3") systemctl restart some-service ;;
    esac
else
    printf '%s\n' "취소됨"
fi

기존의 간단한 menu pattern도 같은 방식으로 사용할 수 있다.

choice=$(whiptail --menu "옵션을 선택하세요" 15 30 4 \
    "1" "설치" \
    "2" "제거" \
    "3" "업데이트" 3>&1 1>&2 2>&3)
 
printf '선택: %s\n' "$choice"

options=$(whiptail --checklist "패키지 선택" 15 40 4 \
    "nginx" "웹 서버" OFF \
    "mysql" "데이터베이스" ON \
    "php" "PHP 언어" OFF 3>&1 1>&2 2>&3)
 
printf '선택된 항목: %s\n' "$options"

tag에 공백이나 quote가 들어갈 수 있으면 기본 결과 문자열을 eval로 해석하지 않는다. 가능하면 단순하고 통제된 tag를 사용하거나 –separate-output과 –output-fd를 조합해 line 단위로 읽는다.

{
    for i in {1..100}; do
        printf '%s\n' "$i"
        sleep 0.1
    done
} | whiptail --gauge "처리 중..." 6 50 0

• Tab: button이나 field 사이를 이동한다.
• Space: checklist 항목을 선택하거나 해제한다.
• Enter: 현재 선택을 확정한다.
• Esc: widget을 취소하고 일반적으로 status 255로 종료한다.
• ↑, ↓, PgUp, PgDn: list나 text를 이동한다.

• widget 결과는 기본적으로 standard error로 출력된다.
• 3>&1 1>&2 2>&3 FD swap 또는 –output-fd를 사용한다.
• command substitution 직후 $?를 저장해 취소 여부를 확인한다.

option parsing을 끝내기 위해 독립된 – token을 widget argument 앞의 적절한 위치에 둔다. 구체적인 placement는 설치본의 manual을 확인하고 test한다.

• 대화형 terminal인지 [ -t 0 ] && [ -t 1 ]로 확인한다.
• TERM 값과 infocmp "$TERM" 결과를 확인한다.
• CI나 cron에는 plain-text 또는 environment-variable 기반 fallback을 제공한다.

• whiptail은 newt를 사용하고 dialog는 일반적으로 ncurses를 사용한다.
• whiptail에는 dialog의 calendar, timebox, tailbox, form 등 여러 widget이 없다.
• 공통 option처럼 보여도 mapping이나 동작이 다를 수 있다. 예를 들어 dialog는 일부 whiptail option을 자체 이름으로 mapping하거나 무시한다.
• 두 implementation 사이의 자동 fallback은 사용 widget과 output을 양쪽에서 test한 뒤 적용한다.

whiptail --help

Box options:
	--msgbox <text> <height> <width>
	--yesno  <text> <height> <width>
	--infobox <text> <height> <width>
	--inputbox <text> <height> <width> [init]
	--passwordbox <text> <height> <width> [init]
	--textbox <file> <height> <width>
	--menu <text> <height> <width> <listheight> [tag item] ...
	--checklist <text> <height> <width> <listheight> [tag item status]...
	--radiolist <text> <height> <width> <listheight> [tag item status]...
	--gauge <text> <height> <width> <percent>
Options: (depend on box-option)
	--clear                         clear screen on exit
	--defaultno                     default no button
	--default-item <string>         set default string
	--fb, --fullbuttons             use full buttons
	--nocancel                      no cancel button
	--yes-button <text>             set text of yes button
	--no-button <text>              set text of no button
	--ok-button <text>              set text of ok button
	--cancel-button <text>          set text of cancel button
	--noitem                        don't display items
	--notags                        don't display tags
	--separate-output               output one line at a time
	--output-fd <fd>                output to fd, not stdout
	--title <title>                 display title
	--backtitle <backtitle>         display backtitle
	--scrolltext                    force vertical scrollbars
	--topleft                       put window in top-left corner
	-h, --help                      print this message
	-v, --version                   print version information

• dialog
• ncurses
• Debian whiptail(1)
• Debian whiptail
• Fedora newt
• Homebrew newt

• codex:: 2026-08-10 기존 command와 switch coverage를 보존해 표준 whiptail:ko page로 migration하고 설치, FD 처리, exit status, 호환성, troubleshooting을 보강함.