파이썬 실행 중 ModuleNotFoundError가 발생하셨나요? 원인 5가지와 단계별 해결법을 예제 코드와 함께 쉽게 설명합니다.
파이썬 코드를 실행했는데 갑자기 이런 오류가 뜬다면?
```
ModuleNotFoundError: No module named 'requests'
```
당황하지 마세요. 이 오류는 파이썬을 사용하다 보면 누구나 한 번쯤 마주치는 흔한 오류입니다. 원인만 정확히 파악하면 5분 안에 해결할 수 있습니다.
ModuleNotFoundError란?
`ModuleNotFoundError`는 파이썬이 `import` 문에서 지정한 모듈을 찾지 못할 때 발생하는 오류입니다. 파이썬 3.6부터 `ImportError`의 하위 클래스로 추가되었으며, 더 명확한 오류 메시지를 제공합니다.
원인 1: 모듈이 설치되지 않음 (가장 흔한 원인)
증상
```
ModuleNotFoundError: No module named 'requests'
```
해결법
터미널(또는 명령 프롬프트)에서 pip으로 설치합니다.
```bash
pip install requests
```
설치 후에도 같은 오류가 난다면 `pip3`을 시도해 보세요.
```bash
pip3 install requests
```
원인 2: 파이썬 버전이 여러 개 설치된 경우
컴퓨터에 Python 2와 Python 3가 함께 설치되어 있거나, 가상환경이 활성화되지 않은 경우 발생합니다.
확인 방법
현재 사용 중인 파이썬이 어디 있는지 확인하세요.
```bash
# Windows
where python
# Mac/Linux
which python
which python3
```
해결법
파이썬 실행 파일과 pip을 일치시켜 설치합니다.
```bash
python -m pip install requests
```
또는
```bash
python3 -m pip install requests
```
`python -m pip`을 사용하면 현재 실행 중인 파이썬에 정확히 설치됩니다.
원인 3: 가상환경(venv) 미활성화
프로젝트에 가상환경을 만들었지만 활성화를 깜빡한 경우입니다.
가상환경 활성화 방법
**Windows:**
```bash
venv\Scripts\activate
```
**Mac/Linux:**
```bash
source venv/bin/activate
```
활성화되면 터미널 앞에 `(venv)`가 붙습니다.
```
(venv) C:\MyProject>
```
이 상태에서 패키지를 설치하고 실행하면 됩니다.
원인 4: 모듈 이름 오타
패키지 이름과 import 이름이 다른 경우가 있습니다.
흔한 예시
| pip 설치 이름 | import 이름 |
|---|---|
| `pip install Pillow` | `import PIL` |
| `pip install scikit-learn` | `import sklearn` |
| `pip install beautifulsoup4` | `import bs4` |
| `pip install opencv-python` | `import cv2` |
설치할 때 이름과 import 이름이 다를 수 있으니 공식 문서를 꼭 확인하세요.
원인 5: 직접 만든 모듈 경로 문제
자신이 만든 `.py` 파일을 import하려는데 오류가 나는 경우입니다.
상황 예시
```
project/
├── main.py
└── utils/
└── helper.py
```
`main.py`에서 `helper.py`를 import하려면:
```python
# 잘못된 방법
import helper
올바른 방법
from utils import helper
또는
from utils.helper import my_function
```
또는 `utils` 폴더 안에 `__init__.py` 파일이 있는지 확인하세요.
```bash
touch utils/__init__.py
```
빠른 진단 체크리스트
오류가 발생했을 때 순서대로 확인해 보세요.
1. `pip list` 명령으로 해당 패키지가 설치되어 있는지 확인
2. `python -m pip install 패키지명`으로 재설치 시도
3. 가상환경을 사용 중이라면 활성화 여부 확인
4. pip 설치 이름과 import 이름이 다른지 확인
5. 자체 모듈이라면 경로와 `__init__.py` 확인
마무리
`ModuleNotFoundError`는 무서운 오류가 아닙니다. 대부분 모듈 미설치 또는 가상환경 미활성화가 원인이며, 위의 방법으로 대부분 해결됩니다.
그래도 해결이 안 된다면 댓글로 오류 메시지 전체를 남겨주세요. 같이 해결해 드리겠습니다!