Typer

Python type hint를 이용해 option, argument, help, shell completion을 생성하는 Click 기반 CLI framework다.

• 작은 script는 typer.run(), 여러 command는 typer.Typer()로 시작한다.
• 함수 parameter의 type annotation과 default 값으로 CLI schema를 만든다.
• 설치되는 typer command로 일반 Python script를 개발 중에 CLI처럼 실행할 수도 있다.

공식 문서는 project dependency와 virtual environment를 함께 관리하는 uv를 우선 안내한다.

# 모든 운영체제: uv project
uv init awesome-project --bare
cd awesome-project
uv add typer
uv run typer --version
 
# pip를 사용하는 Linux / macOS project
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install typer
typer --version

# Windows PowerShell
py -m venv .venv
.venv\Scripts\Activate.ps1
py -m pip install typer
typer --version

Typer가 공식적으로 별도 안내하는 APT, DNF/YUM, Homebrew, winget package는 없다. Python project dependency로 설치한다.

import typer
 
def main(name: str, count: int = 1, formal: bool = False):
    """인사말을 출력합니다."""
    greeting = "안녕하세요" if formal else "안녕"
    for _ in range(count):
        print(f"{greeting}, {name}!")
 
if __name__ == "__main__":
    typer.run(main)

python3 main.py --help
python3 main.py World --count 2 --formal
typer main.py run World --count 2 --formal

• python3 MAIN.py NAME [–count COUNT] [–formal]
• typer MAIN.py run [ARGS…]

import typer
 
app = typer.Typer(help="사용자 관리 CLI")
 
@app.command()
def create(name: str, admin: bool = False):
    """사용자를 생성합니다."""
    typer.echo(f"create {name}, admin={admin}")
 
@app.command()
def delete(name: str, force: bool = False):
    """사용자를 삭제합니다."""
    if not force:
        typer.confirm(f"{name} 사용자를 삭제할까요?", abort=True)
    typer.echo(f"delete {name}")
 
if __name__ == "__main__":
    app()

• python3 USERS.py create NAME [–admin]
• python3 USERS.py delete NAME [–force]

• typer.run(function) : 함수 하나를 즉시 CLI application으로 실행
• typer.Typer() : command group application 생성
• @app.command() : 함수를 subcommand로 등록
• typer.Argument(…) / typer.Option(…) : argument와 option metadata 및 validation 지정
• typer.echo() / typer.secho() : terminal 출력
• typer.confirm() / typer.prompt() : 대화형 입력
• typer.Exit(code=…) / typer.Abort() : 의도된 CLI 종료

typer 개발용 command의 대표 option이다. 정확한 목록은 설치된 version의 typer –help로 확인한다.

• –install-completion : 현재 shell용 completion 설치
• –show-completion : 현재 shell용 completion script 출력
• –version : Typer version 표시
• –help : command help 표시

배포할 CLI는 개발용 typer FILE run 대신 pyproject.toml의 script entry point를 사용한다.

[project]
name = "users-cli"
version = "0.1.0"
dependencies = ["typer"]
 
[project.scripts]
users = "users_cli.main:app"

uv sync
uv run users --help

• type annotation이 없으면 원하는 변환과 help가 생성되지 않을 수 있다.
• option과 positional argument가 예상과 다르면 default 유무와 typer.Option / typer.Argument 선언을 확인한다.
• shell completion 설치 후에는 terminal을 다시 시작하고 같은 virtual environment를 활성화한다.
• application이 커지면 command 함수와 domain logic을 분리한다.

• Typer는 Click 위에 구축되므로 dependency version 제약과 Click 동작도 함께 확인한다.
• 최신 문서의 일부 예제는 Python 3.10+ annotation 문법을 사용한다. 낮은 Python version을 지원하면 호환되는 typing 문법을 사용한다.

이 환경에는 Typer가 설치되어 있지 않아 live help를 복사하지 않았다. 설치한 project environment에서 현재 version의 help를 확인한다.

uv run typer --help
uv run python main.py --help

• Python
• Click
• argparse
• uv
• Typer 공식 문서
• Typer 공식 문서: Install
• Typer 공식 문서: First Steps

• codex:: 2026-08-03 Typer 설치, 단일·복수 command 작성, packaging과 completion 흐름을 정리.