sys — 시스템별 매개변수와 함수

sys 모듈은 인터프리터가 사용하거나 유지하는 몇몇 변수와, 인터프리터와 밀접하게 상호작용하는 함수에 대한 접근을 제공해요. 이 모듈은 언제나 사용할 수 있고, 별도의 언급이 없으면 모든 변수는 읽기 전용이에요.

출처: Python 표준 라이브러리

본문

인터프리터 관련 정보

sys.abiflags 표준 configure 스크립트로 빌드한 POSIX 시스템에서 PEP 3149가 규정한 ABI 플래그를 담고 있어요. 버전 3.2에 추가됨. 버전 3.8에서 변경: 기본 플래그가 빈 문자열이 됐어요(pymalloc을 위한 m 플래그가 제거됨). 가용성: Unix.

sys.argv Python 스크립트에 전달된 명령줄 인자 목록이에요. argv[0]는 스크립트 이름이에요(전체 경로인지는 운영체제에 따라 달라요). -c 옵션으로 실행했다면 argv[0]은 '-c'가 되고, 스크립트 이름을 넘기지 않았다면 빈 문자열이 돼요.

표준 입력이나 명령줄에 주어진 파일 목록을 순회하려면 fileinput 모듈을 보세요. 관련 항목으로 sys.orig_argv도 있어요.

참고: Unix에서 명령줄 인자는 운영체제에서 바이트로 전달돼요. Python은 이를 파일시스템 인코딩과 "surrogateescape" 에러 핸들러로 디코딩해요. 원래 바이트가 필요하면 [os.fsencode(arg) for arg in sys.argv]로 얻을 수 있어요.

sys.audit(event, *args) 감사 이벤트를 발생시키고 활성 감사 훅을 트리거해요. event는 이벤트를 식별하는 문자열이고, args는 이벤트에 대한 추가 정보를 담는 선택적 인자예요. 주어진 이벤트에 대한 인자의 개수와 타입은 공개적이고 안정된 API로 간주되어 릴리스 사이에 바뀌면 안 돼요.

예를 들어 os.chdir이라는 감사 이벤트는 요청된 새 작업 디렉터리를 담는 path라는 인자를 하나 가져요. sys.audit()는 기존 감사 훅을 호출하면서 이벤트 이름과 인자를 전달하고, 어느 훅에서든 처음 발생한 예외를 다시 던져요. 일반적으로 예외가 발생하면 처리하지 말고 가능한 한 빨리 프로세스를 종료해야 해요. 버전 3.8에 추가됨.

sys.byteorder 네이티브 바이트 순서의 표시자예요. 빅엔디안(최상위 바이트 우선) 플랫폼에서는 'big', 리틀엔디안(최하위 바이트 우선) 플랫폼에서는 'little' 값을 가져요.

sys.builtin_module_names 이 Python 인터프리터에 컴파일되어 들어간 모든 모듈의 이름을 담은 문자열 튜플이에요. (modules.keys()는 가져온 모듈만 나열하므로 다른 방법으로는 알 수 없어요.) 관련 항목으로 sys.stdlib_module_names가 있어요.

sys.call_tracing(func, args) 추적이 활성화된 상태에서 func(*args)를 호출해요. 추적 상태는 저장됐다가 나중에 복원돼요. 디버거가 체크포인트에서 다른 코드를 재귀적으로 디버깅하거나 프로파일링할 때 쓰도록 고안됐어요.

sys.copyright Python 인터프리터에 관한 저작권이 담긴 문자열이에요.

sys._clear_type_cache() 내부 타입 캐시를 비워요. 타입 캐시는 속성과 메서드 조회를 빠르게 하는 데 쓰여요. 참조 누수 디버깅 중 불필요한 참조를 버릴 때만 쓰세요. 버전 3.13부터는 더 일반적인 _clear_internal_caches()를 쓰도록 폐기됨.

sys._current_frames() 각 스레드의 식별자를 그 스레드에서 현재 활성인 최상위 스택 프레임에 매핑하는 딕셔너리를 반환해요. traceback 모듈의 함수들이 이런 프레임으로 호출 스택을 구성할 수 있어요. 교착 상태(deadlock) 디버깅에 가장 유용한데, 교착된 스레드의 협조가 필요 없고 그 스레드의 호출 스택은 교착 상태에 있는 동안 얼어붙기 때문이에요. 감사 이벤트 sys._current_frames를 인자 없이 발생시켜요.

sys._current_exceptions() 각 스레드의 식별자를 그 스레드에서 현재 활성인 최상위 예외에 매핑하는 딕셔너리를 반환해요. 예외를 처리 중이 아닌 스레드는 결과 딕셔너리에 포함되지 않아요. 확률적(통계적) 프로파일링에 가장 유용해요. 버전 3.12에서 변경: 각 값이 sys.exc_info()가 반환하던 3-튜플 대신 단일 예외 인스턴스가 됐어요.

sys.breakpointhook() 내장 breakpoint()가 호출하는 훅 함수예요. 기본적으로 pdb 디버거로 들어가지만, 다른 함수로 설정해서 원하는 디버거를 쓸 수 있어요. 기본 구현은 먼저 환경 변수 PYTHONBREAKPOINT를 확인해요. 이 값이 "0"이면 즉시 반환하고(no-op), 설정되지 않았거나 빈 문자열이면 pdb.set_trace()를 호출해요. 그 외에는 점 표기법으로 함수를 가리키는 이름(예: package.subpackage.module.function)으로 보고 해당 함수를 실행해요. PYTHONBREAKPOINT가 가리키는 콜러블을 가져오는 데 문제가 생기면 RuntimeWarning이 보고되고 브레이크포인트는 무시돼요. 버전 3.7에 추가됨.

sys.displayhook(value) value가 None이 아니면 repr(value)를 sys.stdout으로 출력하고 builtins._에 저장해요. repr(value)를 sys.stdout.encoding과 sys.stdout.errors 에러 핸들러(보통 'strict')로 인코딩할 수 없으면 'backslashreplace' 에러 핸들러로 인코딩해요. 대화형 세션에서 표현식 평가 결과에 호출돼요. 의사 코드:

def displayhook(value):
    if value is None:
        return
    # Set '_' to None to avoid recursion
    builtins._ = None
    text = repr(value)
    try:
        sys.stdout.write(text)
    except UnicodeEncodeError:
        bytes = text.encode(sys.stdout.encoding, 'backslashreplace')
        if hasattr(sys.stdout, 'buffer'):
            sys.stdout.buffer.write(bytes)
        else:
            text = bytes.decode(sys.stdout.encoding, 'strict')
            sys.stdout.write(text)
    sys.stdout.write("\n")
    builtins._ = value

버전 3.2에서 변경: UnicodeEncodeError에 'backslashreplace' 에러 핸들러를 사용.

sys.dont_write_bytecode 참이면 소스 모듈을 가져올 때 .pyc 파일을 쓰지 않아요. 초기값은 -B 명령줄 옵션과 PYTHONDONTWRITEBYTECODE 환경 변수에 따라 결정되지만, 직접 설정해서 바이트코드 파일 생성을 제어할 수 있어요.

sys.pycache_prefix 설정되어 있으면(None이 아니면), Python은 소스 트리의 __pycache__ 디렉터리 대신 이 디렉터리를 루트로 하는 병렬 디렉터리 트리에 .pyc 바이트코드 캐시 파일을 쓰고 읽어요. 상대 경로는 현재 작업 디렉터리 기준으로 해석돼요. 초기값은 -X pycache_prefix=PATH 옵션 또는 PYTHONPYCACHEPREFIX 환경 변수에 기반해요. 버전 3.8에 추가됨.

sys.excepthook(type, value, traceback) 주어진 traceback과 예외를 sys.stderr에 출력해요. SystemExit 이외의 예외가 잡히지 않고 발생하면 인터프리터는 세 인자(예외 클래스, 예외 인스턴스, traceback 객체)로 sys.excepthook을 호출해요. 다른 삼-인자 함수를 sys.excepthook에 할당해서 최상위 예외 처리를 커스터마이즈할 수 있어요. 잡히지 않은 예외가 발생하면 감사 이벤트 sys.excepthook이 hook, type, value, traceback 인자로 발생해요.

sys.__breakpointhook__, sys.__displayhook__, sys.__excepthook__, sys.__unraisablehook__ 프로그램 시작 시점의 breakpointhook, displayhook, excepthook, unraisablehook의 원래 값을 담고 있어요. 이 값들이 깨지거나 대체된 객체로 바뀌었을 때 복원할 수 있도록 저장해둔 거예요. __breakpointhook__는 3.7, __unraisablehook__는 3.8에 추가됨.

sys.exception() 예외 핸들러가 실행 중일 때(except나 except* 절 등) 그 핸들러가 잡은 예외 인스턴스를 반환해요. 중첩된 핸들러에서는 가장 안쪽 핸들러가 처리하는 예외만 접근할 수 있어요. 실행 중인 예외 핸들러가 없으면 None을 반환해요. 버전 3.11에 추가됨.

sys.exc_info() 처리된 예외의 구식 표현을 반환해요. 예외 e가 현재 처리 중이라면 (type(e), e, e.__traceback__) 튜플을 반환해요. 즉 예외 타입(BaseException의 서브클래스), 예외 자체, 그리고 예외가 마지막으로 발생한 시점의 호출 스택을 캡슐화한 traceback 객체예요. 처리 중인 예외가 없으면 None 세 개짜리 튜플을 반환해요. 버전 3.11에서 변경: type과 traceback 필드가 value에서 파생됨.

sys.exec_prefix 플랫폼 의존 Python 파일이 설치된 사이트별 디렉터리 접두사 문자열이에요. 기본적으로 /usr/local이에요. 모든 구성 파일(예: pyconfig.h)은 exec_prefix/lib/pythonX.Y/config에, 공유 라이브러리 모듈은 exec_prefix/lib/pythonX.Y/lib-dynload에 설치돼요. 가상 환경에서는 base_exec_prefix로 원래 설치 위치를 알 수 있어요. 버전 3.14에서 변경: 가상 환경에서 prefix/exec_prefix가 site 대신 경로 초기화로 설정됨.

sys.executable 이해가 되는 시스템에서 Python 인터프리터 실행 바이너리의 절대 경로 문자열이에요. 실제 경로를 가져올 수 없으면 빈 문자열이나 None이 돼요.

sys.exit([arg]) SystemExit 예외를 발생시켜 인터프리터를 종료하려는 의사를 알려요. 선택적 인자 arg는 종료 상태를 나타내는 정수(기본 0)나 다른 타입의 객체일 수 있어요. 정수 0은 성공적인 종료, 0이 아닌 값은 비정상 종료로 여겨져요. 다른 타입 객체를 넘기면 None은 0과 같고, 그 외 객체는 stderr로 출력된 뒤 종료 코드 1로 끝나요. 특히 sys.exit("some error message")는 오류 발생 시 프로그램을 빠르게 종료하는 방법이에요. exit()은 "단지" 예외를 발생시키는 것이므로 메인 스레드에서 호출되고 예외가 가로채지 않을 때만 프로세스를 종료해요. 버전 3.6에서 변경: SystemExit 후 정리 중 에러가 나면 종료 상태가 120이 됨.

sys.flags 명령줄 플래그의 상태를 노출하는 named tuple이에요. 이름으로만 접근해야 하고 속성은 읽기 전용이에요. 주요 속성과 대응 플래그:

flags.debug - -d
flags.inspect, flags.interactive - -i
flags.isolated - -I
flags.optimize - -O or -OO
flags.dont_write_bytecode - -B
flags.no_user_site - -s
flags.no_site - -S
flags.ignore_environment - -E
flags.verbose - -v
flags.bytes_warning - -b
flags.quiet - -q
flags.hash_randomization - -R
flags.dev_mode - -X dev (Python 개발 모드)
flags.utf8_mode - -X utf8
flags.safe_path - -P
flags.int_max_str_digits - -X int_max_str_digits
flags.warn_default_encoding - -X warn_default_encoding
flags.gil - -X gil and PYTHON_GIL
flags.thread_inherit_context - -X thread_inherit_context and PYTHON_THREAD_INHERIT_CONTEXT
flags.context_aware_warnings - -X context_aware_warnings and PYTHON_CONTEXT_AWARE_WARNINGS

sys.float_info float 타입에 대한 정보를 담는 named tuple이에요. C 표준 헤더 float.h에 정의된 부동소수점 상수들에 대응해요. 주요 속성:

float_info.epsilon (DBL_EPSILON) — 1.0과 그보다 큰 최소 float 값 사이의 차이. math.ulp() 참고.
float_info.dig (DBL_DIG) — float로 충실히 표현할 수 있는 최대 십진 자릿수.
float_info.mant_dig (DBL_MANT_DIG) — significand의 base-radix 자릿수.
float_info.max (DBL_MAX) — 표현 가능한 최대 유한 양수 float.
float_info.max_exp (DBL_MAX_EXP), float_info.max_10_exp (DBL_MAX_10_EXP)
float_info.min (DBL_MIN) — 표현 가능한 최소 정규화 양수 float.
float_info.min_exp (DBL_MIN_EXP), float_info.min_10_exp (DBL_MIN_10_EXP)
float_info.radix (FLT_RADIX) — 지수 표현의 밑.
float_info.rounds (FLT_ROUNDS) — 반올림 모드(-1: 판정 불가, 0: 0으로, 1: 가장 가까운 값으로, 2: +무한으로, 3: -무한으로).

sys.float_info.dig에 대해 더 설명하면, 유효 숫자가 sys.float_info.dig개 이하인 십진 문자열 s는 float로 변환했다가 다시 되돌리면 같은 값을 나타내요:

>>> import sys
>>> sys.float_info.dig
15
>>> s = '3.14159265358979'    # decimal string with 15 significant digits
>>> format(float(s), '.15g')  # convert to float and back -> same value
'3.14159265358979'

하지만 sys.float_info.dig보다 많은 유효 숫자를 가진 문자열은 항상 그렇지는 않아요:

>>> s = '9876543211234567'    # 16 significant digits is too many!
>>> format(float(s), '.16g')  # conversion changes value
'9876543211234568'

sys.float_repr_style float에 대한 repr()의 동작을 나타내는 문자열이에요. 'short'이면 유한한 float x에 대해 repr(x)가 float(repr(x)) == x를 만족하는 짧은 문자열을 만들려 해요(Python 3.1 이후의 일반 동작). 그 외에는 'legacy'로 3.1 이전처럼 동작해요. 버전 3.1에 추가됨.

sys.getallocatedblocks() 인터프리터가 현재 할당한 메모리 블록 수를 반환해요(크기 무관). 메모리 누수 추적과 디버깅에 주로 유용해요. 버전 3.4에 추가됨.

sys.getdefaultencoding() 'utf-8'을 반환해요. str.encode() 같은 메서드에서 쓰는 기본 문자열 인코딩 이름이에요.

sys.getdlopenflags() dlopen() 호출에 쓰이는 플래그의 현재 값을 반환해요. 플래그 값의 기호 이름은 os 모듈(RTLD_xxx 상수, 예: os.RTLD_LAZY)에서 찾을 수 있어요. 가용성: Unix.

sys.getfilesystemencoding() 파일시스템 인코딩을 얻어요. Unicode 파일 이름과 바이트 파일 이름 사이를 변환하는 데 파일시스템 에러 핸들러와 함께 쓰여요. 호환성을 위해 파일 이름은 항상 str을 쓰는 게 좋아요. os.fsencode()와 os.fsdecode()를 사용해서 올바른 인코딩과 에러 모드를 보장하세요. 버전 3.2에서 변경: 결과가 더 이상 None이 될 수 없음. 3.6에서 Windows가 'mbcs'를 보장하지 않음. 3.7에서 UTF-8 모드가 활성이면 'utf-8' 반환.

sys.getfilesystemencodeerrors() 파일시스템 에러 핸들러를 얻어요. 버전 3.6에 추가됨.

sys.get_int_max_str_digits() 정수-문자열 변환 길이 제한의 현재 값을 반환해요. set_int_max_str_digits() 참고. 버전 3.11에 추가됨.

sys.getrefcount(object) 객체의 참조 카운트를 반환해요. 반환값은 보통 예상보다 하나 높은데, getrefcount()에 인자로 전달된 (임시) 참조를 포함하기 때문이에요. 불멸(immortal) 객체는 실제 참조 수와 무관한 매우 큰 refcount를 가지므로 0이나 1 외에는 정확하다고 믿지 마세요. 버전 3.12에서 변경: 불멸 객체는 실제와 맞지 않는 매우 큰 refcount를 가짐.

sys.getrecursionlimit() 재귀 한계의 현재 값, 즉 Python 인터프리터 스택의 최대 깊이를 반환해요. 이 한계는 무한 재귀로 인한 C 스택 오버플로와 크래시를 막아요. setrecursionlimit()로 설정할 수 있어요.

sys.getsizeof(object[, default]) 객체의 크기를 바이트 단위로 반환해요. 객체가 직접 점유하는 메모리만 계산하고, 참조하는 객체의 메모리는 포함하지 않아요. 객체가 크기를 가져올 방법을 제공하지 않으면 default가 주어진 경우 이를 반환하고, 아니면 TypeError를 발생시켜요. getsizeof()는 객체의 __sizeof__ 메서드를 호출하고, 가비지 컬렉터가 관리한다면 GC 오버헤드를 추가해요.

sys.getswitchinterval() 인터프리터의 "스레드 스위치 간격"을 초 단위로 반환해요. setswitchinterval() 참고. 버전 3.2에 추가됨.

sys._getframe([depth]) 호출 스택에서 프레임 객체를 반환해요. 선택적 정수 depth가 주어지면 스택 맨 위에서 그만큼 아래에 있는 프레임을 반환하고, 스택보다 깊으면 ValueError를 발생시켜요. 기본 depth는 0으로 호출 스택 맨 위 프레임을 반환해요. 감사 이벤트 sys._getframe을 frame 인자로 발생시켜요. CPython 구현 세부사항: 내부 전용.

sys.getprofile() setprofile()로 설정된 프로파일 함수를 얻어요.

sys.gettrace() settrace()로 설정된 추적 함수를 얻어요. CPython 구현 세부사항: 디버거/프로파일러/커버리지 도구 구현 전용.

sys.getwindowsversion() 현재 실행 중인 Windows 버전을 설명하는 named tuple을 반환해요. 구성 요소는 major, minor, build, platform, service_pack, service_pack_minor, service_pack_major, suite_mask, product_type, platform_version이에요. product_type은 1(VER_NT_WORKSTATION 워크스테이션), 2(VER_NT_DOMAIN_CONTROLLER 도메인 컨트롤러), 3(VER_NT_SERVER 서버) 중 하나예요. Win32 GetVersionEx()를 감싸요. 가용성: Windows.

sys.get_asyncgen_hooks() (firstiter, finalizer) 형태의 namedtuple과 비슷한 asyncgen_hooks 객체를 반환해요. 각각 비동기 제너레이터 이터레이터를 인자로 받는 함수이거나 None이에요. 버전 3.6에 추가됨(잠정, PEP 525, PEP 411).

sys.get_coroutine_origin_tracking_depth() set_coroutine_origin_tracking_depth()가 설정한 현재 코루틴 원점 추적 깊이를 얻어요. 버전 3.7에 추가됨. 디버깅 용도로만.

sys.hash_info 숫자 해시 구현의 매개변수를 주는 named tuple이에요. 주요 속성: hash_info.width(해시 값 비트 폭), hash_info.modulus(숫자 해시 방식의 소수 계수 P), hash_info.inf(양의 무한대의 해시 값), hash_info.nan(더 이상 사용 안 함), hash_info.imag(복소수의 허수부 곱셈기), hash_info.algorithm(str/bytes/memoryview 해시 알고리즘 이름), hash_info.hash_bits, hash_info.seed_bits, hash_info.cutoff. 버전 3.2에 추가됨; 3.4에서 algorithm, hash_bits, seed_bits, cutoff 추가.

sys.hexversion 버전 번호를 단일 정수로 인코딩한 값이에요. 버전마다 증가함이 보장돼요. 예를 들어 Python 1.5.2 이상인지 검사하려면:

if sys.hexversion >= 0x010502F0:
    # use some advanced feature
    ...
else:
    # use an alternative implementation or warn the user
    ...

sys.implementation 현재 실행 중인 Python 인터프리터 구현에 대한 정보를 담는 객체예요. 모든 구현에 존재해야 하는 속성: name(구현 식별자, 예: 'cpython', 소문자 보장), version(sys.version_info와 같은 형식의 named tuple — 이는 언어 버전이 아니라 구현 버전을 나타냄), hexversion, cache_tag(캐시된 모듈 파일 이름에 쓰이는 태그, 예: 'cpython-33', None이면 모듈 캐싱 비활성), supports_isolated_interpreters(여러 고립 해석기 지원 여부). 버전 3.3에 추가됨; 3.14에서 supports_isolated_interpreters 추가. PEP 421 참고.

sys.int_info Python 내부 정수 표현에 대한 정보를 담는 named tuple이에요. 읽기 전용. 주요 속성: int_info.bits_per_digit(각 자릿수가 담는 비트 수 — 정수는 내부적으로 밑 2**int_info.bits_per_digit로 저장), int_info.sizeof_digit(자릿수를 나타내는 C 타입의 바이트 크기), int_info.default_max_str_digits, int_info.str_digits_check_threshold. 버전 3.1에 추가됨; 3.11에서 default_max_str_digits와 str_digits_check_threshold 추가.

sys.__interactivehook__ 이 속성이 존재하면 인터프리터가 대화형 모드로 시작될 때 자동으로(인자 없이) 호출돼요. PYTHONSTARTUP 파일을 읽은 뒤에 호출되므로 그 파일에서 이 훅을 설정할 수 있어요. site 모듈이 설정해요. 버전 3.4에 추가됨.

sys.intern(string) 문자열을 "interned"(인턴)된 문자열 테이블에 넣고 interned 문자열을 반환해요(그 문자열 자체 또는 사본). 사전 조회에서 약간의 성능을 얻는 데 유용해요 — 키가 interned되면 비교를 문자열 비교 대신 포인터 비교로 할 수 있기 때문이에요. interned 문자열은 불멸이 아니므로 intern()의 반환값에 참조를 유지해야 해요.

sys._is_gil_enabled() GIL이 활성이면 True, 비활성이면 False를 반환해요. 버전 3.13에 추가됨.

sys.is_finalizing() 메인 Python 인터프리터가 종료 중이면 True, 아니면 False를 반환해요. PythonFinalizationError 예외 참고. 버전 3.5에 추가됨.

sys.last_exc 항상 정의되지는 않는 변수로, 예외가 처리되지 않아 인터프리터가 오류 메시지와 스택 traceback을 출력할 때 그 예외 인스턴스로 설정돼요. 대화형 사용자가 오류를 일으킨 명령을 다시 실행하지 않고 사후 디버깅(post-mortem)을 하도록 하려는 용도예요(보통 import pdb; pdb.pm()). 버전 3.12에 추가됨.

sys.maxsize Py_ssize_t 타입 변수가 취할 수 있는 최대값을 주는 정수예요. 보통 32비트 플랫폼에서 2**31 - 1, 64비트 플랫폼에서 2**63 - 1이에요.

sys.maxunicode 가장 큰 Unicode 코드 포인트 값이에요, 즉 1114111(0x10FFFF). 3.3에서 변경: PEP 393 이전에는 UCS-2/UCS-4 설정에 따라 0xFFFF 또는 0x10FFFF였음.

sys.meta_path 가져올 모듈을 찾을 수 있는지 확인하기 위해 find_spec() 메서드가 호출되는 메타 경로 파인더 객체들의 리스트예요. 기본적으로 Python의 기본 가져오기 의미론을 구현하는 항목들을 담아요. 자세한 내용은 importlib.abc.MetaPathFinder와 importlib.machinery.ModuleSpec을 보세요. 버전 3.4에서 변경: 모듈 스펙 도입(PEP 451). 3.12에서 find_module() 대체 제거.

sys.modules 모듈 이름을 이미 로드된 모듈에 매핑하는 딕셔너리예요. 강제 재로딩 같은 꼼수에 조작될 수 있지만, 딕셔너리 전체를 바꾸는 건 예상대로 동작하지 않을 수 있어요. 순회할 때는 크기가 변할 수 있으니 항상 sys.modules.copy()나 tuple(sys.modules)를 쓰세요.

sys.orig_argv Python 실행 파일에 전달된 원래 명령줄 인자들의 리스트예요. sys.orig_argv의 요소는 Python 인터프리터에 대한 인자이고, sys.argv의 요소는 사용자 프로그램에 대한 인자예요. 버전 3.10에 추가됨.

sys.path 모듈 검색 경로를 지정하는 문자열 리스트예요. PYTHONPATH 환경 변수와 설치 의존 기본값으로부터 초기화돼요. 시작 시 잠재적으로 안전하지 않은 경로가 sys.path 앞에 추가돼요:

python -m module 명령줄: 현재 작업 디렉터리를 앞에 추가.
python script.py 명령줄: 스크립트의 디렉터리를 앞에 추가(심볼릭 링크면 해석).
python -c code와 python(REPL) 명령줄: 빈 문자열(현재 작업 디렉터리)을 앞에 추가.

이 경로를 추가하지 않으려면 -P 옵션이나 PYTHONSAFEPATH 환경 변수를 쓰세요. 프로그램은 이 목록을 자유롭게 수정할 수 있어요. sys.path에는 문자열만 추가해야 해요. 확장 방법은 site 모듈(.pth 파일) 참고.

sys.path_hooks 경로 인자를 받아 그 경로에 대한 파인더를 만들려 시도하는 콜러블들의 리스트예요. 파인더가 만들어지면 콜러블이 반환하고, 아니면 ImportError를 발생시켜야 해요. PEP 302 참고.

sys.path_importer_cache 파인더 객체의 캐시 역할을 하는 딕셔너리예요. 키는 sys.path_hooks에 전달된 경로들이고 값은 찾은 파인더예요. PEP 302 참고.

sys.platform 플랫폼 식별자를 담는 문자열이에요. 알려진 값: AIX 'aix', Android 'android', Emscripten 'emscripten', FreeBSD 'freebsd', iOS 'ios', Linux 'linux', macOS 'darwin', Windows 'win32', Windows/Cygwin 'cygwin', WASI 'wasi'. 표에 없는 Unix 시스템에서는 uname -s의 소문자 OS 이름에 uname -r의 첫 부분을 덧붙인 값(예: 'sunos5')이에요. 특정 시스템을 검사할 땐:

if sys.platform.startswith('sunos'):
    # SunOS-specific code here...

3.3에서 변경: Linux에서 메이저 버전 포함 안 함('linux2'/'linux3' 대신 항상 'linux'). 3.8 AIX, 3.13 Android('android'), 3.14 FreeBSD에서도 마찬가지. os.name은 더 거친 세분화를 주고 platform 모듈이 상세한 검사를 제공해요.

sys.platlibdir 플랫폼별 라이브러리 디렉터리 이름이에요. 표준 라이브러리와 설치된 확장 모듈의 경로를 만드는 데 쓰여요. 대부분 플랫폼에서 "lib"과 같고, Fedora/SuSE 64비트에서는 "lib64"이에요. 결과적으로 sys.path에 /usr/lib64/pythonX.Y/, /usr/lib64/pythonX.Y/lib-dynload/, /usr/lib/pythonX.Y/site-packages/, /usr/lib64/pythonX.Y/site-packages/ 같은 경로가 생겨요. 버전 3.9에 추가됨.

sys.prefix 플랫폼 독립 Python 파일이 설치된 사이트별 디렉터리 접두사 문자열이에요. Unix 기본값은 /usr/local이에요. 가상 환경에서는 base_prefix로 원래 설치 위치를 알 수 있어요. 버전 3.14에서 변경: 가상 환경에서 prefix/exec_prefix가 site 대신 경로 초기화로 설정됨.

sys.ps1, sys.ps2 인터프리터의 기본/보조 프롬프트를 지정하는 문자열이에요. 대화형 모드일 때만 정의되고 초기값은 '>>> '와 '... '이에요. 문자열이 아닌 객체를 할당하면 그 str()이 매번 다시 평가돼서 동적 프롬프트를 구현할 수 있어요.

sys.setdlopenflags(n) 인터프리터가 dlopen() 호출(예: 확장 모듈 로드)에 쓰는 플래그를 설정해요. sys.setdlopenflags(0)로 호출하면 모듈 가져올 때 심볼을 지연(lazy) 해석하게 해요. 확장 모듈 간에 심볼을 공유하려면 sys.setdlopenflags(os.RTLD_GLOBAL)로 호출해요. 기호 이름은 os 모듈에서 찾을 수 있어요. 가용성: Unix.

sys.set_int_max_str_digits(maxdigits) 이 인터프리터가 사용하는 정수-문자열 변환 길이 제한을 설정해요. get_int_max_str_digits() 참고. 버전 3.11에 추가됨.

sys.setprofile(profilefunc) 시스템 프로파일 함수를 설정해요. Python으로 소스 코드 프로파일러를 구현할 수 있게 해줘요. 프로파일 함수는 세 인자 frame, event, arg를 받아야 하고, event는 'call', 'return', 'c_call', 'c_return', 'c_exception' 중 하나예요. 반환값은 사용되지 않아 그냥 None을 반환해도 돼요. 프로파일 함수에 오류가 있으면 스스로 해제돼요. 감사 이벤트 sys.setprofile을 인자 없이 발생시켜요.

sys.setrecursionlimit(limit) Python 인터프리터 스택의 최대 깊이를 limit으로 설정해요. 무한 재귀로 인한 C 스택 오버플로와 크래시를 막아요. 너무 높게 잡으면 크래시가 날 수 있으니 주의해서 설정해야 해요. 현재 재귀 깊이에서 새 한계가 너무 낮으면 RecursionError가 발생해요. 3.5.1에서 변경.

sys.setswitchinterval(interval) 인터프리터의 스레드 스위치 간격(초)을 설정해요. 이 부동소수점 값은 동시에 실행되는 Python 스레드에 할당되는 "타임슬라이스"의 이상적 지속 시간을 결정해요. 실제 값은 더 길 수 있고, 간격 끝에 어떤 스레드가 스케줄될지는 운영체제가 결정해요. 버전 3.2에 추가됨.

sys.settrace(tracefunc) 시스템 추적 함수를 설정해요. Python으로 소스 코드 디버거를 구현할 수 있게 해줘요. 함수는 스레드별로 적용돼요. 추적 함수는 세 인자 frame, event, arg를 받고, event는 'call', 'line', 'return', 'exception', 'opcode' 중 하나예요. 새 로컬 스코프에 들어갈 때마다('call') 호출되고, 새 스코프에 쓰일 로컬 추적 함수 참조를 반환하거나(추적 안 하려면 None) 반환해요. 추적 함수에 오류가 있으면 settrace(None)을 호출한 것처럼 해제돼요.

감사 이벤트 sys.settrace를 인자 없이 발생시켜요. CPython 구현 세부사항: 디버거/프로파일러/커버리지 도구 구현 전용. 3.7에서 변경: 'opcode' 이벤트 타입과 f_trace_lines, f_trace_opcodes 속성 추가.

sys.set_asyncgen_hooks([firstiter] [, finalizer]) 비동기 제너레이터 이터레이터를 인자로 받는 두 선택적 키워드 인자를 받아요. firstiter는 제너레이터가 처음 순회될 때, finalizer는 가비지 컬렉션 직전에 호출돼요. PEP 525 참고. 버전 3.6에 추가됨(잠정, PEP 411).

sys.set_coroutine_origin_tracking_depth(depth) 코루틴 원점 추적을 활성화/비활성화해요. 활성화하면 코루틴 객체의 cr_origin 속성에 (filename, line number, function name) 튜플들로 구성된 생성 위치 traceback이 담겨요. 0보다 큰 depth로 활성화하고, 0으로 비활성화해요. 스레드별 설정이에요. 버전 3.7에 추가됨. 디버깅 용도로만.

sys.activate_stack_trampoline(backend, /) 스택 프로파일러 트램폴린 백엔드를 활성화해요. 지원되는 유일한 백엔드는 "perf"예요. JIT가 활성이면 활성화할 수 없어요. 가용성: Linux. 버전 3.12에 추가됨.

sys.deactivate_stack_trampoline() 현재 스택 프로파일러 트램폴린 백엔드를 비활성화해요. 활성화된 게 없으면 아무 효과도 없어요. 가용성: Linux. 버전 3.12에 추가됨.

sys.is_stack_trampoline_active() 스택 프로파일러 트램폴린이 활성이면 True를 반환해요. 가용성: Linux. 버전 3.12에 추가됨.

sys.remote_exec(pid, script) 주어진 pid의 원격 프로세스에서 Python 코드를 담은 script 파일을 실행해요. 이 함수는 즉시 반환하고, 코드는 신호가 처리되는 것처럼 대상 프로세스 메인 스레드가 다음 기회에 실행해요. 원격 프로세스는 로컬과 같은 메이저/마이너 버전의 CPython을 실행해야 해요. PEP 768 참고. 가용성: Unix, Windows. 버전 3.14에 추가됨.

sys._enablelegacywindowsfsencoding() 파일시스템 인코딩과 에러 핸들러를 각각 'mbcs'와 'replace'로 바꿔 3.6 이전 버전과 일관되게 해요. PYTHONLEGACYWINDOWSFSENCODING 환경 변수를 정의하는 것과 같아요. 가용성: Windows. 3.6 추가, 3.13부터 폐기(3.16에서 제거).

표준 스트림

sys.stdin, sys.stdout, sys.stderr 인터프리터가 표준 입출력과 오류에 사용하는 파일 객체들이에요.

stdin은 모든 대화형 입력(input() 호출 포함)에 쓰여요.
stdout은 print()와 표현식 문의 출력, input()의 프롬프트에 쓰여요.
인터프리터 자체의 프롬프트와 오류 메시지는 stderr로 가요.

대화형일 때 stdout은 라인 버퍼링되고, 그 외에는 일반 텍스트 파일처럼 블록 버퍼링돼요. stderr는 두 경우 모두 라인 버퍼링이에요. -u 옵션이나 PYTHONUNBUFFERED 환경 변수로 두 스트림을 모두 버퍼링 없이 만들 수 있어요.

참고: 표준 스트림에 이진 데이터를 쓰거나 읽으려면 기본 이진 buffer 객체를 쓰세요. 예를 들어 stdout에 바이트를 쓰려면 sys.stdout.buffer.write(b'abc')를 사용해요. 다만 라이브러리를 작성한다면 표준 스트림이 buffer 속성을 지원하지 않는 io.StringIO 같은 파일류 객체로 대체될 수 있다는 점을 유의하세요.

sys.__stdin__, sys.__stdout__, sys.__stderr__ 프로그램 시작 시점의 stdin, stdout, stderr의 원래 값을 담고 있어요. 종료(finalization) 중에 쓰이며, sys.std* 객체가 리다이렉트되었어도 실제 표준 스트림에 출력하는 데 유용해요. 특정 조건에서 stdin/stdout/stderr와 원래 값들이 None일 수 있는데, 보통 콘솔에 연결되지 않은 Windows GUI 앱과 pythonw로 시작한 앱의 경우예요.

sys.stdlib_module_names 표준 라이브러리 모듈 이름을 담은 frozenset이에요. 모든 플랫폼에서 같고, 일부 플랫폼에서 사용 불가한 모듈과 빌드에서 비활성화된 모듈도 나열돼요. 순수 Python, 내장, frozen, 확장 모듈이 모두 포함되고 테스트 모듈은 제외돼요. 패키지의 경우 메인 패키지만 나열돼요. 예를 들어 email 패키지는 나열되지만 email.mime 서브패키지와 email.message 서브모듈은 나열되지 않아요. sys.builtin_module_names 참고. 버전 3.10에 추가됨.

sys.thread_info 스레드 구현에 대한 정보를 담는 named tuple이에요. thread_info.name은 "nt"(Windows 스레드), "pthread"(POSIX 스레드), "pthread-stubs", "solaris" 중 하나예요. thread_info.lock은 "semaphore" 또는 "mutex+cond"(알 수 없으면 None)예요. thread_info.version은 스레드 라이브러리의 이름과 버전, 또는 None이에요. 버전 3.3에 추가됨.

sys.tracebacklimit 정수로 설정하면 처리되지 않은 예외가 발생할 때 출력되는 traceback 정보의 최대 단계 수를 결정해요. 기본값은 1000이에요. 0 이하로 설정하면 모든 traceback 정보가 억제되고 예외 타입과 값만 출력돼요.

sys.unraisablehook(unraisable, /) 처리할 수 없는(unraisable) 예외를 처리해요. 예외가 발생했지만 Python이 처리할 방법이 없을 때(예: 소멸자가 예외를 발생시키거나 gc.collect() 중) 호출돼요. unraisable 인자는 다음 속성을 가져요: exc_type(예외 타입), exc_value(예외 값, None 가능), exc_traceback(traceback, None 가능), err_msg(오류 메시지, None 가능), object(예외를 일으킨 객체, None 가능). 기본 훅은 err_msg와 object를 f'{err_msg}: {object!r}' 형식으로 만들어요. 커스텀 훅에서 exc_value를 저장하면 참조 사이클을 만들 수 있으니 명시적으로 비워줘야 해요. 감사 이벤트 sys.unraisablehook이 hook, unraisable 인자로 발생해요. 버전 3.8에 추가됨.

sys.version Python 인터프리터의 버전 번호와 빌드 번호, 컴파일러에 대한 추가 정보를 담는 문자열이에요. 여기서 버전 정보를 추출하지 말고, version_info와 platform 모듈의 함수를 쓰세요.

sys.api_version C API 버전으로, C 매크로 PYTHON_API_VERSION과 같아요. 역호환을 위해 정의돼요.

sys.version_info 버전 번호의 다섯 구성 요소를 담는 튜플이에요: major, minor, micro, releaselevel, serial. releaselevel을 제외한 값은 정수이고, releaselevel은 'alpha', 'beta', 'candidate', 'final' 중 하나예요. Python 2.0에 해당하는 값은 (2, 0, 0, 'final', 0)이에요. 이름으로도 접근할 수 있어서 sys.version_info[0]은 sys.version_info.major와 같아요. 3.1에서 변경: 이름 있는 구성 요소 속성 추가.

sys.warnoptions warnings 프레임워크의 구현 세부사항이에요. 수정하지 마세요. warnings 모듈 참고.

sys.winver Windows 플랫폼에서 레지스트리 키를 만드는 데 쓰는 버전 번호예요. Python DLL의 문자열 리소스 1000으로 저장돼 있어요. 값은 보통 실행 중인 Python 인터프리터의 메이저/마이너 버전이에요. 가용성: Windows.

sys.monitoring 모니터링 이벤트 등록 콜백과 제어를 위한 함수와 상수를 담는 네임스페이스예요. sys.monitoring 문서 참고.

sys._xoptions -X 명령줄 옵션으로 전달된 다양한 구현별 플래그의 딕셔너리예요. 옵션 이름은 명시적으로 주어졌으면 값으로, 아니면 True로 매핑돼요. 예:

$ ./python -Xa=b -Xc
Python 3.2a3+ (py3k, Oct 16 2010, 20:14:50)
[GCC 4.4.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys._xoptions
{'a': 'b', 'c': True}

CPython 구현 세부사항: -X로 전달된 옵션에 접근하는 CPython 고유 방식. 3.2에 추가됨.

더 알아보기

site 모듈 — .pth 파일로 sys.path를 확장하는 방법.
os 모듈 — 파이썬 프로그램에서 운영체제 기능에 종속적인 인터페이스. 파일시스템 인코딩 관련 함수(os.fsencode(), os.fsdecode()) 참고.
importlib — sys.meta_path, sys.path_hooks의 가져오기 메커니즘.
warnings 모듈 — sys.warnoptions 관련 경고 프레임워크.
platform 모듈 — sys.platform보다 상세한 플랫폼 검사.