sys

Python interpreter가 전달한 command-line argument, 표준 입출력 stream, 종료 상태에 접근하는 표준 라이브러리 모듈이다.

• sys.argv로 원시 command-line argument를 읽는다.
• sys.stdin, sys.stdout, sys.stderr로 표준 stream을 다룬다.
• sys.exit()로 shell에 종료 상태를 전달한다.
• argument validation과 자동 help가 필요하면 argparse, Typer, Click 같은 parser를 사용한다.

sys는 항상 사용할 수 있는 Python 기본 모듈이며 별도 설치가 필요하지 않다.

python3 --version
python3 -c "import sys; print(sys.version)"

import sys
 
def main() -> int:
    if len(sys.argv) != 2:
        print(f"Usage: {sys.argv[0]} NAME", file=sys.stderr)
        return 2
 
    print(f"Hello, {sys.argv[1]}!")
    return 0
 
if __name__ == "__main__":
    raise SystemExit(main())

python3 hello.py World
python3 hello.py

종료 상태는 POSIX shell에서 echo $?로 확인할 수 있다.

• python3 HELLO.py NAME
• sys.argv[0] : script 이름; 실행 방식에 따라 전체 경로, -c, 빈 문자열 등이 될 수 있음
• sys.argv[1:] : application에 전달된 나머지 argument

• sys.argv : Python 문자열로 decoding된 command-line argument 목록
• sys.orig_argv : Python executable 자체에 전달된 원래 argument 목록
• sys.stdin / sys.stdout / sys.stderr : text 표준 stream
• sys.stdin.buffer / sys.stdout.buffer : binary stream이 제공되는 환경에서 byte 입출력
• sys.exit(code) : SystemExit을 발생시켜 종료; 0은 성공, 0이 아닌 값은 실패
• sys.executable : 현재 Python interpreter executable 경로
• sys.path : module 검색 경로
• sys.version_info : 실행 중인 Python version 정보

import sys
 
for line in sys.stdin:
    sys.stdout.write(line.upper())

printf '%s\n' alpha beta | python3 upper.py > output.txt

import sys
 
def main() -> int:
    print("configuration file not found", file=sys.stderr)
    return 1
 
if __name__ == "__main__":
    sys.exit(main())

sys.exit("message")는 message를 stderr에 쓰고 상태 1로 종료하는 간단한 형태지만, 큰 application에서는 main()이 정수 상태를 반환하게 하면 테스트하기 쉽다.

import subprocess
import sys
 
subprocess.run([sys.executable, "-m", "pip", "--version"], check=True)

• sys.argv는 이미 shell parsing을 거친 값이다. 공백, wildcard, quote 동작은 먼저 사용 중인 shell 규칙을 따른다.
• Unix에서 원래 argument byte가 꼭 필요하면 공식 문서의 권장 방식인 [os.fsencode(arg) for arg in sys.argv]를 고려한다.
• sys.exit()는 내부적으로 SystemExit을 발생시킨다. main thread 밖에서 호출하거나 예외를 잡으면 process가 종료되지 않을 수 있다.
• output이 pipe나 file로 redirect되면 buffering 동작이 terminal과 다를 수 있다. 즉시 출력이 필요하면 print(…, flush=True) 또는 Python -u option을 사용한다.

• sys는 항상 존재하지만 일부 attribute는 interpreter 구현 또는 운영체제에 따라 다르다.
• shell에 전달할 종료 코드는 portability를 위해 일반적으로 0부터 127 범위에서 사용한다.

sys 자체는 python -m sys로 실행하는 CLI가 아니다. 직접 만든 script에서 usage를 구현하거나 argparse 같은 parser로 –help를 제공한다.

• Python
• argparse
• Click
• Python 공식 문서: sys
• Python 공식 문서: Command line and environment

• codex:: 2026-08-03 sys.argv, 표준 stream, 종료 코드 중심의 Python CLI 기본 사용법을 정리.