argparse

Python 표준 라이브러리에서 option, positional argument, subcommand를 선언하고 sys.argv를 검증·변환하는 CLI parser다.

• argparse.ArgumentParser에 argument 규칙을 등록하고 parse_args()로 해석한다.
• -h/–help, usage, 오류 메시지를 자동 생성한다.
• 외부 dependency 없이 Python 3에서 사용할 수 있다.

argparse는 Python 3.2부터 포함된 표준 라이브러리이므로 별도 설치가 필요하지 않다.

python3 --version
python3 -c "import argparse; print(argparse.__file__)"

Windows에서 Python Launcher를 사용하면 py로 바꿔 실행할 수 있다.

import argparse
 
parser = argparse.ArgumentParser(description="파일을 지정 횟수만큼 처리합니다.")
parser.add_argument("path", help="처리할 파일")
parser.add_argument("-n", "--count", type=int, default=1, help="반복 횟수")
parser.add_argument("--verbose", action="store_true", help="상세 출력")
args = parser.parse_args()
 
for _ in range(args.count):
    print(args.path)

python3 app.py --help
python3 app.py --count 3 README.md

• python3 APP.py PATH [OPTIONS]
• -n, –count COUNT: 값을 int로 변환하며 기본값은 1
• –verbose: 지정 여부를 bool로 저장
• -h, –help: 자동 생성된 도움말을 표시하고 종료

• ArgumentParser(prog, description, epilog, …) : parser와 help 기본 정보를 생성
• add_argument(name_or_flags, …) : positional argument 또는 option 등록
• parse_args(args=None) : 기본적으로 sys.argv[1:]을 해석하고 알 수 없는 argument에는 오류 발생
• parse_known_args() : 알려진 값과 나머지 argument를 나눠 반환
• add_subparsers() : git commit 같은 subcommand 구조 생성
• set_defaults() : parser 또는 subparser별 callback과 기본값 연결
• format_help() / print_help() : 도움말 문자열 반환 또는 출력

• action="store_true" / action="store_false" : 값 없는 boolean flag
• type=int 또는 사용자 함수 : 입력값 변환과 검증
• choices=(…) : 허용 값 제한
• default=… : option이 생략됐을 때의 값
• required=True : optional-style option을 필수로 지정
• nargs="?", "*", "+" 또는 정수 : 소비할 argument 개수
• dest="name" : 결과 Namespace의 attribute 이름 지정
• metavar="NAME" : help에 표시할 값 이름 지정
• help="…" : argument 설명; 기본값 표시는 ArgumentDefaultsHelpFormatter 활용

import argparse
 
def cmd_add(args):
    print(f"add: {args.name}")
 
parser = argparse.ArgumentParser(prog="project")
subparsers = parser.add_subparsers(dest="command", required=True)
 
add_parser = subparsers.add_parser("add", help="항목 추가")
add_parser.add_argument("name")
add_parser.set_defaults(func=cmd_add)
 
args = parser.parse_args()
args.func(args)

python3 project.py --help
python3 project.py add demo

• python3 PROJECT.py add NAME

• 음수 값을 positional argument로 전달할 때 option으로 오인되면 – 뒤에 둔다: python3 app.py – -1.
• shell에서 공백을 포함한 값은 먼저 분리되므로 따옴표로 묶는다: –name "Jane Doe".
• library code에서 parse_args()를 직접 호출하면 오류 시 SystemExit이 발생한다. parser 구성과 실행 entry point를 분리하면 테스트하기 쉽다.
• 단순한 sys.argv indexing보다 입력 검증과 자동 help가 필요하면 argparse를 사용한다.

• Python 3.9부터 exit_on_error를 지원한다.
• Python 3.14의 suggest_on_error와 color help 같은 최신 기능을 사용하면 이전 Python과 호환되지 않을 수 있으므로 최소 Python version을 확인한다.

argparse 자체는 python -m argparse로 사용하는 독립 CLI가 아니다. 작성한 application에서 다음 명령으로 생성된 help를 확인한다.

python3 app.py --help
python3 app.py SUBCOMMAND --help

• Python
• sys
• Typer
• Click
• Python 공식 문서: argparse
• Python 공식 문서: argparse tutorial

• codex:: 2026-08-03 argparse CLI 작성 흐름, 핵심 API, subcommand 예제와 호환성 주의를 정리.