import 문을 통해 다른 파이썬 파일을 불러올 때, 파이썬은 내부적으로 파일을 찾기 위해 sys.path와 PYTHONPATH에 있는 경로를 탐색합니다. 이 두 변수를 적절히 수정해 임의의 디렉터리에 있는 파이썬 파일을 손쉽게 불러올 수 있습니다.

sys.path에 append()로 경로 추가 link

sys.path는 디렉터리의 경로들이 기록된 문자열 리스트입니다. 이 리스트에 경로를 추가하면 해당 경로에 있는 파이썬 파일을 import 문으로 불러올 수 있습니다.

예시:

먼저 아무 파이썬 파일을 하나 만듭시다. 내용은 상관 없습니다. 이 예시에서는 /opt/common.py에 만들겠습니다:

# 아무 내용도 없음

이제 /home/ubuntu/example.py를 만듭니다:

import sys
sys.path.append("/opt")
import common

예시에서 sys.path.append("/opt")를 통해 /opt 디렉터리를 추가했습니다. 이로 인해 /opt/common.py를 import할 수 있게 됩니다.

sys.path의 기본값 link

sys.path에는 파이썬에 의해 기본적으로 몇 가지 경로가 미리 추가되어 있습니다.

.py 파일이 속한 디렉터리의 절대 경로 link

sys.path에는 가장 먼저 .py 파일이 속한 디렉터리의 절대 경로가 추가됩니다1.

특정 파이썬 파일을 실행하는 것 대신, 파이썬 인터프리터에서 직접 print(sys.path)를 실행하면 인터프리터를 실행할 당시의 경로(현재 작업 디렉터리)가 sys.path에 추가됩니다2.

예시:

먼저 테스트 용 파일을 만듭니다. 여기서는 /home/ubuntu에 example.py라는 이름으로 만들겠습니다:

import sys
print(sys.path)

실행 결과:

[`'/home/ubuntu'`, ...]

리스트의 첫 번째 값으로 '/home/ubuntu'가 들어있는 것을 확인할 수 있습니다.

예시:

python3을 실행해 파이썬 인터프리터에서 다음 내용을 입력합니다:

>>> import sys
>>> print(sys.path)

실행 결과 (일부 생략):

[`''`, ...]

앞의 예시와 달리 빈 문자열인 ''이 리스트 맨 앞에 존재하는 것을 확인할 수 있습니다. 빈 문자열은 유효한 상대 경로로, 현재 디렉터리를 의미합니다.

PYTHONPATH 환경 변수 link

PYTHONPATH 환경 변수에 경로를 추가하면, 파이썬은 이 경로들을 sys.path에 추가해줍니다.

이를 통해 파이썬 코드 내부에서 뿐만 아니라 파이썬 코드 밖에서도 sys.path를 조작할 수 있습니다.

PYTHONPATH에는 sys.path에 추가할 여러 경로들이 들어갑니다. 리눅스에서는 /foo:/bar처럼 :로 두 경로를 구분하고, 윈도우에서는 /foo;/bar처럼 ;로 두 경로를 구분합니다. (PATH 환경 변수와 동일한 방식)3

예시:

테스트 용 파일을 하나 만듭니다:

import sys
print(sys.path)

다음과 같이 PYTHONPATH 환경 변수에 /foo와 /bar를 넣은 채로 python3 명령어를 실행합니다:

PYTHONPATH=/foo:/bar python3 example.py

실행 결과 (일부 생략):

[..., '/foo', '/bar', ...]

'/foo', '/bar'가 추가된 것을 확인할 수 있습니다.

기타 기본 경로 link

이외에도 sys.path에는 파이썬에 포함된 여러 내장 모듈 등을 탐색하기 위한 기본 경로가 들어갑니다. 이 경로들은 운영 체제나 파이썬 버전에 따라 다릅니다4.

예시:

테스트 용 파일을 하나 만듭니다:

import sys
print(sys.path)

실행 결과 (일부 생략):

[..., `'/usr/lib/python36.zip'`, `'/usr/lib/python3.6'`, `'/usr/lib/python3.6/lib-dynload'`,
`'/usr/local/lib/python3.6/dist-packages'`, `'/usr/lib/python3/dist-packages'`]

'/usr/lib/python36.zip', '/usr/lib/python3.6', '/usr/lib/python3.6/lib-dynload' 등 내장 모듈을 위한 여러 경로들을 확인할 수 있습니다.

참고:

sys.path에는 디렉터리 경로뿐만 아니라 '/usr/lib/python36.zip'처럼 압축 파일도 추가할 수 있습니다. 자세한 내용은 zipimport 모듈을 참고하세요.

주의: sys.path의 순서 link

import는 sys.path 리스트에 들어있는 경로들을 탐색하며 불러올 파이썬 파일을 찾습니다. 리스트에 들어있는 맨 처음 경로부터 탐색을 시작합니다. 특정 경로에서 불러올 파일을 찾았다면 남은 경로를 더 찾아보지 않고 탐색을 중지합니다5.

sys.path의 기본값은 이 문서에서 언급한 순서대로 추가됩니다6:

  1. .py 파일이 속한 디렉터리의 절대 경로
  2. PYTHONPATH 환경 변수
  3. 기타 기본 경로

만약 내장 모듈과 같은 이름으로 로컬 파일을 만들게 되면, 위의 순서로 인해 로컬 파일을 우선하여 불러옵니다7.

참고:

내장 모듈을 덮어쓰는 현상으로 인해 발견하기 어려운 오류가 발생할 수 있습니다. 자세한 내용은 [<파이썬 내장="" 모듈과="" 동일한="" 이름="" 피하기="">](/avoid-python-builtin-module-names.html)를 참고하세요.

  1. The Module Search Path - The Python Tutorial

    The directory containing the input script

    ↩

  2. The Module Search Path - The Python Tutorial

    (or the current directory when no file is specified)

    ↩

  3. PYTHONPATH - Python Setup and Usage

    The format is the same as the shell’s PATH: one or more directory pathnames separated by os.pathsep (e.g. colons on Unix or semicolons on Windows).

    ↩

  4. The Module Search Path - The Python Tutorial

    The installation-dependent default.

    ↩

  5. The Module Search Path - The Python Tutorial

    The directory containing the script being run is placed at the beginning of the search path, ahead of the standard library path.

    ↩

  6. The Module Search Path - The Python Tutorial

    • The directory containing the input script (or the current directory when no file is specified).
    • PYTHONPATH (a list of directory names, with the same syntax as the shell variable PATH).
    • The installation-dependent default.

    ↩

  7. The Module Search Path - The Python Tutorial

    This means that scripts in that directory will be loaded instead of modules of the same name in the library directory. This is an error unless the replacement is intended.

    ↩