11. Python ImportError & ModuleNotFoundError(모듈/경로 문제) 완벽 가이드

이 글에서는 Python 프로젝트에서 흔히 만나는 ImportError와 그 하위 클래스인 ModuleNotFoundError의 정의, 주요 발생 원인, 대표적인 예제와 실행 결과, 해결 방법 및 디버깅 팁을 단계별로 정리합니다. 또한, 다음 챕터인 FileNotFoundError: 파일 또는 경로 없음 문제 예고로 마무리합니다.

1. ImportError & ModuleNotFoundError란?

ImportError는 Python이 import 문으로 모듈을 찾거나 로드하는 과정에서 오류가 발생했을 때 발생하는 예외입니다. ModuleNotFoundError는 지정한 이름의 모듈이 전혀 발견되지 않을 때 발생하는 ImportError의 하위 클래스입니다. Python 3.6 이상에서 도입되었으며, 주로 패키지가 설치되지 않았거나 경로가 잘못 설정된 경우에 발생합니다.

2. 주요 발생 원인

• 패키지 미설치: pip 또는 conda 등으로 모듈이 설치되지 않은 상태에서 import할 때
• 모듈 이름 철자 오류: 대소문자나 오타로 인해 잘못된 이름을 사용했을 때
• 프로젝트 구조 및 경로 설정 문제: sys.path에 올바른 경로가 포함되지 않거나, 상대경로가 잘못 지정된 경우
• 상대/절대 import 혼용 오류: 패키지 내에서 상대경로(import .module)와 절대경로(import package.module)를 혼용할 때
• 가상환경 설정 오류: 올바른 가상환경이 활성화되지 않아 전역 혹은 다른 환경의 패키지를 참조할 때

3. 실습 예제

아래 코드를 실행하면 ModuleNotFoundError가 발생하는 대표적인 예시를 확인할 수 있습니다.

# 예제: 설치되지 않은 패키지 import
import nonexistent_package   # ModuleNotFoundError: No module named 'nonexistent_package'

# 예제: 잘못된 상대경로 import
# 프로젝트 구조:
# myproj/
#   ├── main.py
#   └── utils/
#       └── helper.py
#
# helper.py 안에서:
# from .helper import func  # ModuleNotFoundError: attempted relative import with no known parent package

4. 실행 결과 및 설명

위 코드를 실행하면 다음과 같은 에러 메시지가 출력됩니다:

Traceback (most recent call last):
  File "example.py", line 1, in 
    import nonexistent_package
ModuleNotFoundError: No module named 'nonexistent_package'

Traceback (most recent call last):
  File "main.py", line 1, in 
    from .helper import func
ModuleNotFoundError: attempted relative import with no known parent package

첫 번째 메시지는 지정한 패키지가 설치되지 않았음을, 두 번째 메시지는 잘못된 상대경로 import 시도임을 명확히 알려줍니다.

5. 해결 방법 & 디버깅 팁

1. 패키지 설치 확인
   ```bash pip install ``` 설치 여부를 확인하고, 설치되지 않았다면 위 명령으로 패키지를 추가하세요 :contentReference[oaicite:9]{index=9}.
2. 철자 및 대소문자 검토
   모듈 이름을 정확히 입력했는지, 대소문자가 일치하는지 확인하세요.
3. sys.path 점검
   ```python import sys print(sys.path) ``` 해당 경로에 모듈이 위치했는지 확인하고, 필요 시 `sys.path.append()` 또는 `PYTHONPATH` 설정을 추가하세요.
4. 상대/절대 import 통일
   프로젝트 내에서 상대경로와 절대경로 중 한 가지 방식을 일관되게 사용하세요.
5. 가상환경 활성화
   ```bash source venv/bin/activate # Unix/Mac .\venv\Scripts\activate # Windows ``` 올바른 가상환경이 활성화된 상태에서 패키지를 설치 및 실행하세요.

6. 정리 및 다음 단계

이번 챕터에서는 ImportError와 ModuleNotFoundError의 정의, 주요 원인, 예제와 해결 방법을 살펴보았습니다. 패키지 설치와 경로 설정, import 방식 통일 및 가상환경 관리를 통해 오류를 예방할 수 있습니다. 다음 챕터에서는 FileNotFoundError: 파일 또는 경로 없음 문제를 다룰 예정이니 많은 기대 부탁드립니다.