sys.path 모듈 검색 경로의 초기화

모듈 검색 경로(module search path)는 Python이 시작할 때 초기화돼요. 이 검색 경로는 sys.path에서 접근할 수 있어요.

검색 경로의 첫 번째 항목은 입력 스크립트를 담고 있는 디렉터리예요(스크립트가 있다면). 그렇지 않으면 첫 번째 항목은 현재 디렉터리인데, 이는 대화형 셸이나 -c 명령, -m 모듈을 실행할 때의 경우예요.

PYTHONPATH 환경 변수는 검색 경로에 디렉터리를 추가할 때 자주 쓰여요. 이 환경 변수가 발견되면 그 내용이 모듈 검색 경로에 추가돼요.

참고 — PYTHONPATH는 설치된 모든 Python 버전/환경에 영향을 줘요. 셸 프로파일이나 전역 환경 변수에 이걸 설정하는 것은 조심하세요. site 모듈이 아래에서 언급하는 것처럼 더 세밀한 기법을 제공해요.

다음에 추가되는 항목은 표준 Python 모듈과, 이 모듈들이 의존하는 확장 모듈들을 담고 있는 디렉터리들이에요. 확장 모듈은 Windows에서는 .pyd 파일이고 다른 플랫폼에서는 .so 파일이에요. 플랫폼 독립적인 Python 모듈이 담긴 디렉터리를 prefix라고 하고, 확장 모듈이 담긴 디렉터리를 exec_prefix라고 해요.

PYTHONHOME 환경 변수로 prefix와 exec_prefix의 위치를 설정할 수 있어요. 그렇지 않으면 이 디렉터리들은 Python 실행 파일을 출발점으로 삼아 여러 '랜드마크(landmark)' 파일과 디렉터리를 찾아서 알아내요. 심볼릭 링크는 모두 따라가서 실제 Python 실행 파일 위치가 검색 출발점으로 쓰인다는 점을 기억하세요. 이 Python 실행 파일 위치를 home이라고 해요.

home이 결정되면, 먼저 pythonmajorversionminorversion.zip(python311.zip)을 찾아 prefix 디렉터리를 찾아요. Windows에서는 이 zip 아카이브를 home에서 찾고, Unix에서는 lib에 있을 것으로 기대해요. 아카이브가 없어도 기대되는 zip 아카이브 위치는 모듈 검색 경로에 추가된다는 점을 주목하세요. 아카이브를 찾지 못하면, Windows의 Python은 Lib\os.py를 찾아 prefix 검색을 계속해요. Unix의 Python은 lib/pythonmajorversion.minorversion/os.py(lib/python3.11/os.py)를 찾아요. Windows에서는 prefix와 exec_prefix가 같지만, 다른 플랫폼에서는 lib/pythonmajorversion.minorversion/lib-dynload(lib/python3.11/lib-dynload)를 찾아 exec_prefix의 앵커로 써요. 어떤 플랫폼에서는 lib가 lib64나 다른 값일 수 있어요. sys.platlibdir과 PYTHONPLATLIBDIR을 참고하세요.

일단 찾으면 prefix와 exec_prefix를 각각 sys.base_prefix와 sys.base_exec_prefix에서 사용할 수 있어요.

만약 PYTHONHOME이 설정되어 있지 않고, 메인 실행 파일 곁이나 그 부모 디렉터리에서 pyvenv.cfg 파일이 발견되면, sys.prefix와 sys.exec_prefix는 pyvenv.cfg를 담고 있는 디렉터리로 설정돼요. 그렇지 않으면 각각 sys.base_prefix와 sys.base_exec_prefix와 같은 값으로 설정돼요. 이 동작은 가상 환경(Virtual Environments)에서 쓰여요.

마지막으로 site 모듈이 처리되고 site-packages 디렉터리들이 모듈 검색 경로에 추가돼요. 검색 경로를 커스터마이즈하는 흔한 방법은 site 모듈 문서에 설명된 대로 sitecustomize나 usercustomize 모듈을 만드는 거예요.

참고 — 특정 명령줄 옵션들이 경로 계산에 추가로 영향을 줄 수 있어요. 자세한 내용은 -E, -I, -s, -S를 참고하세요.

버전 3.14에서 변경: sys.prefix와 sys.exec_prefix가 이제 경로 초기화 중에 pyvenv.cfg 디렉터리로 설정됨. 이전에는 이 작업이 site가 했기 때문에 -S의 영향을 받았어요.

출처: Python 표준 라이브러리

본문

가상 환경 (Virtual Environments)

가상 환경은 자기 prefix에 pyvenv.cfg 파일을 두는데, 이로 인해 sys.prefix와 sys.exec_prefix가 기본 설치(base installation)가 아니라 가상 환경을 가리키게 돼요.

기본 설치의 prefix와 exec_prefix 값은 sys.base_prefix와 sys.base_exec_prefix에서 쓸 수 있어요.

pyvenv.cfg는 가상 환경을 식별하는 표식으로 쓰일 뿐 아니라, site 초기화를 구성하는 데도 쓰일 수 있어요. site의 가상 환경 문서를 참고하세요.

참고 — PYTHONHOME은 pyvenv.cfg 감지를 덮어써요.

참고 — '가상 환경'을 구현하는 다른 방법들도 있어요. 이 문서는 venv처럼 pyvenv.cfg 메커니즘을 바탕으로 한 구현을 가리켜요. 대부분의 가상 환경 구현은 venv가 세운 모델을 따르지만, 거기서 벗어나는 특이한 구현도 있을 수 있어요.

._pth 파일

sys.path를 완전히 덮어쓰려면 공유 라이브러리나 실행 파일과 같은 이름의 ._pth 파일(python._pth 또는 python311._pth)을 만들면 돼요. 공유 라이브러리 경로는 Windows에서는 항상 알려져 있지만, 다른 플랫폼에서는 없을 수도 있어요. ._pth 파일에는 sys.path에 추가할 각 경로를 한 줄씩 지정해요. 공유 라이브러리 이름을 기반으로 한 파일이 실행 파일 기반의 파일을 덮어써서, 원하면 런타임을 로드하는 어떤 프로그램에서든 경로를 제한할 수 있어요.

파일이 존재하면 모든 레지스트리와 환경 변수가 무시되고, 격리(isolated) 모드가 활성화되며, 파일에 있는 한 줄이 import site를 지정하지 않는 한 site는 임포트되지 않아요. 빈 경로와 #로 시작하는 줄은 무시돼요. 각 경로는 파일 위치에 대해 절대적이거나 상대적일 수 있어요. site 외의 import 문은 허용되지 않고, 임의의 코드를 지정할 수 없어요.

.pth 파일(밑줄 없이)은 import site가 지정되면 site 모듈이 정상적으로 처리한다는 점을 주목하세요.

임베디드 Python

Python이 다른 애플리케이션 안에 임베디드되면 Py_InitializeFromConfig()와 PyConfig 구조체로 Python을 초기화할 수 있어요. 경로와 관련된 자세한 내용은 Python Path Configuration에서 설명해요.

더 알아보기

모듈 찾기(Windows 자세한 참고 사항).
Unix 플랫폼에서 Python 사용하기(Unix 관련 사항).