[PYTHON] 상대 경로 임포트 ImportError 해결을 위한 3가지 방법과 절대 경로 차이 분석

ImportError

 

 

파이썬 개발을 하다 보면 프로젝트 구조가 깊어짐에 따라 from . import module 또는 from ..sub import func와 같은 상대 경로 임포트(Relative Import)를 사용하게 됩니다. 하지만 실행 시 마주하게 되는 ImportError: attempted relative import with no known parent package라는 에러 메시지는 많은 개발자를 당혹스럽게 만듭니다. 본 포스팅에서는 2026년 최신 파이썬 실행 환경을 기준으로 이 문제가 발생하는 근본적인 원인을 진단하고, 실무에서 바로 적용 가능한 3가지 해결 방법을 상세히 제시합니다.

---

1. ImportError: 왜 발생하는가? 근본 원인 분석

파이썬의 상대 경로 임포트는 현재 모듈의 __name__ 속성에 의존합니다. 모듈을 직접 실행(python script.py)하면 __name__은 '__main__'이 되며, 이 상태에서는 파이썬 인터프리터가 해당 파일의 상위 패키지 정보를 알 수 없게 됩니다. 즉, '부모가 누구인지 모르는' 상태에서 상대적인 위치를 찾으려 하기 때문에 에러가 발생하는 것입니다.

---

2. 절대 경로 vs 상대 경로 임포트 핵심 차이 비교

임포트 방식의 선택은 프로젝트의 확장성과 유지보수성에 큰 영향을 미칩니다. 두 방식의 차이점을 표로 정리했습니다.

비교 항목	절대 경로 임포트 (Absolute)	상대 경로 임포트 (Relative)
구문 예시	from my_pkg.md1 import func	from .md1 import func
기준점	프로젝트 최상위 루트 (sys.path)	현재 모듈의 위치
실행 편의성	어디서든 실행 가능	패키지로서 실행 필수
가독성	명확하지만 경로가 길어질 수 있음	간결하지만 구조 파악이 어려움
권장 상황	대규모 프로젝트, 외부 라이브러리	패키지 내부 모듈 간 긴밀한 결합

---

3. 상대 경로 임포트 문제 해결을 위한 3가지 방법

방법 01. 모듈 실행 시 -m 플래그 사용하기

가장 표준적인 해결 방법입니다. 스크립트를 파일 경로로 실행하는 대신, 파이썬 인터프리터에게 이 파일이 특정 패키지의 일부임을 알려주며 실행하는 방식입니다.

# 에러 발생: python my_pkg/main.py
# 해결 방법: python -m my_pkg.main

방법 02. sys.path를 활용한 경로 동적 추가

로컬 테스트나 스크립트 도구 제작 시, 최상위 디렉토리를 파이썬 검색 경로에 강제로 포함시키는 방법입니다. 다만, 코드의 이식성을 저해할 수 있으므로 주의해서 사용해야 합니다.

방법 03. PYTHONPATH 환경 변수 설정

터미널 세션이나 시스템 환경 변수에 프로젝트 루트 경로를 등록하여, 파이썬이 항상 해당 위치를 기준으로 모듈을 찾을 수 있도록 설정하는 해결책입니다.

---

4. 실전 가이드 및 샘플 예제 (Sample Example)

다음과 같은 프로젝트 구조에서 발생하는 에러 해결 과정을 살펴보겠습니다.

프로젝트 구조

project_root/
├── main.py
└── my_app/
    ├── __init__.py
    ├── core.py
    └── utils.py (여기서 core.py를 상대 임포트 시도)
    

[Before] 에러가 발생하는 코드 (utils.py)

# utils.py 내부
from .core import setup_logger  # ImportError 발생 가능 지점

def run():
    setup_logger()
    print("Utils is running...")
    

[After] 정상 실행을 위한 호출 방법

터미널의 위치를 project_root로 이동한 후 아래와 같이 실행합니다.

# 1. 패키지 모듈로 실행 (권장)
python -m my_app.utils

# 2. 만약 main.py에서 utils를 호출한다면 절대 경로 권장
# main.py 내부: from my_app import utils
    

---

5. 전문가의 조언: 패키지 설계 시 고려사항

상대 경로 임포트 에러를 원천적으로 방지하기 위한 설계 해결 전략입니다.

• 엔트리 포인트 분리: 실제 실행 로직이 담긴 스크립트(main.py)는 패키지 외부에 두거나 최상위에 배치하십시오.
• PEP 8 준수: 파이썬 공식 가이드는 패키지 내부가 아닌 이상 절대 경로 임포트를 지향합니다.
• __init__.py 활용: 패키지 초기화 파일을 통해 외부로 노출할 인터페이스를 미리 정리하면 임포트 경로가 단순해집니다.

---

6. 결론: 유연한 임포트 시스템 구축

파이썬의 임포트 시스템은 강력하지만 실행 맥락에 따라 민감하게 반응합니다. ImportError를 마주했을 때 단순히 코드를 수정하기보다, 현재 실행 환경이 '패키지 내부'인지 '개별 스크립트'인지를 먼저 파악하는 것이 중요합니다. 2026년 대규모 마이크로서비스 환경에서는 가급적 절대 경로를 사용하여 구조적 명확성을 확보하는 것이 가장 현명한 해결 방법입니다.

---

내용의 출처

• Python Software Foundation: "Modules - Intra-package References"
• PEP 328: "Imports: Multi-Line and Absolute/Relative"
• Real Python: "Absolute vs Relative Imports in Python"
• Stack Overflow: "Manually fixing sys.path for relative imports"