{{tag>[cli python argparse standard-library argument-parser]}}

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

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

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

<code bash>
python3 --version
python3 -c "import argparse; print(argparse.__file__)"
</code>

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

===== Usage =====
<code python>
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)
</code>

<code bash>
python3 app.py --help
python3 app.py --count 3 README.md
</code>

  * ''<color #c3c3c3>**python3**</color> <color #7092be>APP.py PATH</color> <color #22b14c>[OPTIONS]</color>''
  * ''<color #22b14c>**-n, --count**</color> <color #7092be>COUNT</color>'': 값을 ''int''로 변환하며 기본값은 ''1''
  * ''<color #22b14c>**--verbose**</color>'': 지정 여부를 ''bool''로 저장
  * ''<color #22b14c>**-h, --help**</color>'': 자동 생성된 도움말을 표시하고 종료

===== Core API =====
  * ''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()'' : 도움말 문자열 반환 또는 출력

===== Common add_argument Options =====
  * ''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'' 활용

===== Examples =====
==== Subcommand와 callback ====
<code python>
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)
</code>

<code bash>
python3 project.py --help
python3 project.py add demo
</code>

  * ''<color #c3c3c3>**python3**</color> <color #7092be>PROJECT.py</color> <color #ff7f27>add</color> <color #7092be>NAME</color>''

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

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

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

<code bash>
python3 app.py --help
python3 app.py SUBCOMMAND --help
</code>

===== See Also =====
  * [[python|Python]]
  * [[python:sys:ko|sys]]
  * [[python:typer:ko|Typer]]
  * [[python:click:ko|Click]]
  * [[https://docs.python.org/3/library/argparse.html|Python 공식 문서: argparse]]
  * [[https://docs.python.org/3/howto/argparse.html|Python 공식 문서: argparse tutorial]]

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

{{indexmenu>.#1|js}}