sys.path 모듈 검색 경로의 초기화¶
Python이 시작될 때 모듈 검색 경로가 초기화됩니다. 이 모듈 검색 경로는 sys.path 를 통해 접근할 수 있습니다.
모듈 검색 경로의 첫 번째 항목은 입력 스크립트가 있는 디렉터리입니다(스크립트가 있는 경우). 그렇지 않은 경우, 첫 번째 항목은 현재 디렉터리이며, 이는 대화형 셸을 실행하거나 -c 명령 또는 -m 모듈을 실행할 때 해당됩니다.
PYTHONPATH 환경 변수는 검색 경로에 디렉터리를 추가하는 데 자주 사용됩니다. 이 환경 변수가 발견되면 그 내용이 모듈 검색 경로에 추가됩니다.
참고
PYTHONPATH 은 설치된 모든 Python 버전 및 환경에 영향을 미칩니다. 셸 프로파일이나 전역 환경 변수에 이 값을 설정할 때 주의하십시오. 아래에 언급된 것처럼 site 모듈이 더 세밀한 기법을 제공합니다.
The next items added are the directories containing standard Python modules as
well as any extension modules that these modules depend on. Extension
modules are .pyd files on Windows and .so files on other platforms. The
directory with the platform-independent Python modules is called prefix.
The directory with the extension modules is called exec_prefix.
PYTHONHOME 환경 변수는 prefix 및 exec_prefix 위치를 설정하는 데 사용될 수 있습니다. 그렇지 않은 경우, Python 실행 파일을 시작점으로 사용하여 다양한 ‘랜드마크’ 파일과 디렉터리를 찾아 이 경로들을 결정합니다. 이때 모든 심볼릭 링크를 따라가므로 실제 Python 실행 파일의 위치가 검색의 시작점으로 사용됩니다. Python 실행 파일의 위치는 home 이라고 합니다.
home 이 결정되면 먼저 pythonmajorversionminorversion.zip (python311.zip)을 찾아 prefix 디렉터리를 찾습니다. Windows에서는 home 에서 zip 아카이브를 검색하고, Unix에서는 lib 에서 아카이브가 있을 것으로 예상합니다. 아카이브가 존재하지 않더라도 해당 위치는 모듈 검색 경로에 추가됩니다. 아카이브를 찾지 못한 경우, Windows의 Python은 Libos.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 와 동일한 값으로 설정됩니다. 이 설정은 가상 환경 에서 사용됩니다.
마지막으로, site 모듈이 처리되고 site-packages 디렉터리가 모듈 검색 경로에 추가됩니다. PYTHONUSERBASE 환경 변수는 사용자용 site-packages를 찾는 위치를 제어하며, PYTHONNOUSERSITE 환경 변수는 사용자용 site-packages 탐색을 완전히 중단합니다. 검색 경로를 사용자 정의하는 일반적인 방법은 site 모듈 문서에 설명된 대로 sitecustomize 또는 usercustomize 모듈을 생성하는 것입니다.
버전 3.14에서 변경: sys.prefix 와 sys.exec_prefix 는 이제 경로 초기화 중에 pyvenv.cfg 디렉터리로 설정됩니다. 이전에는 site 에 의해 수행되어 -S 의 영향을 받았습니다.
가상 환경¶
가상 환경은 프리픽스에 pyvenv.cfg 파일을 배치하며, 이로 인해 sys.prefix 와 sys.exec_prefix 가 기본 설치 경로 대신 해당 가상 환경을 가리키게 됩니다.
기본 설치의 prefix 및 exec_prefix 값은 sys.base_prefix 와 sys.base_exec_prefix 에서 확인할 수 있습니다.
pyvenv.cfg 는 가상 환경을 식별하는 표식으로 사용될 뿐만 아니라, site 초기화 구성을 위해서도 사용될 수 있습니다. 자세한 내용은 site 의 가상 환경 문서 를 참조하십시오.
참고
PYTHONHOME`은 ``pyvenv.cfg` 탐색을 무시하고 우선 적용됩니다.
참고
가상 환경을 구현하는 다른 방법들도 있습니다. 이 문서는 많은 가상 환경 구현체들이 따르는 pyvenv.cfg 메커니즘 기반의 구현 방식(예: venv)에 대해 설명합니다.
_pth 파일¶
sys.path 를 완전히 재정의하려면 공유 라이브러리 또는 실행 파일과 동일한 이름의 ._pth 파일(예: python._pth 또는 python311._pth)을 생성하십시오. 공유 라이브러리 경로는 Windows에서 항상 확인 가능하지만, 다른 플랫폼에서는 제공되지 않을 수 있습니다. ._pth 파일 내에 sys.path 에 추가할 경로를 한 줄씩 입력하십시오. 공유 라이브러리 이름을 기반으로 하는 파일은 실행 파일을 기반으로 하는 파일을 우선하며, 이를 통해 필요한 경우 런타임을 로드하는 모든 프로그램에 대해 경로를 제한할 수 있습니다.
When the file exists, all registry and environment variables are ignored,
isolated mode is enabled, and site is not imported unless one line in the
file specifies import site. Blank paths and lines starting with # are
ignored. Each path may be absolute or relative to the location of the file.
Import statements other than to site are not permitted, and arbitrary code
cannot be specified.
import site``가 지정된 경우, 앞에 언더스코어가 없는 ``.pth 파일이 site 모듈에 의해 정상적으로 처리됨을 유의하십시오.
내장된 파이썬¶
파이썬이 다른 애플리케이션에 내장된 경우, Py_InitializeFromConfig() 와 PyConfig 구조를 사용하여 파이썬을 초기화할 수 있습니다. 경로 관련 세부 사항은 Python 경로 설정 에서 설명합니다.
더 보기
Windows 관련 상세 내용은 모듈 찾기 를 참조하십시오.
Unix 관련 상세 내용은 유닉스 플랫폼에서 파이썬 사용하기 를 참조하십시오.