ModuleNotFoundError: No module named 해결

문제 해결 / module-not-found-error.html

Python에서 가장 자주 만나는 import 오류의 원인과 진단·해결 절차를 정리했습니다. 대부분은 실행 중인 파이썬 환경 불일치입니다.

💬 "pip install 했는데 왜 No module named 뜨나요?"

ModuleNotFoundError: No module named 'xxx'는 Python에서 가장 자주 만나는 오류입니다. 좋은 소식은 원인 대부분이 하나라는 점입니다. 실행 중인 Python과 패키지가 설치된 Python이 다릅니다.

증상

$ python myscript.py
ModuleNotFoundError: No module named 'requests'

그런데 분명히 pip install requests를 했습니다. 여기서 대부분이 멈추고 검색을 시작합니다.

원인 (자주 나오는 순)

• 환경 불일치: 터미널 하나에는 가상환경이 켜져 있고, 실행은 다른 파이썬으로 한 경우
• 설치 자체 누락: pip3와 python3가 다른 곳을 가리키는 경우 (시스템에 파이썬이 여러 개 있을 때)
• 상대 import 문제: 패키지 내부에서 from . import x 대신 import x로 써서 생기는 경우
• pip 자체가 없는 환경: 일부 최소 이미지나 새로 만든 가상환경에서 pip가 비어 있는 경우

진단 — 30초 만에 확인

아래 명령으로 "지금 이 셸의 파이썬"과 "패키지가 있는지"를 함께 확인합니다.

# 1) 지금 쓰는 파이썬이 어디인지
python3 -c "import sys; print(sys.executable)"

# 2) 패키지가 이 파이썬에 있는지
python3 -c "import importlib.util as u; print(u.find_spec('requests'))"

# 3) pip이 어느 파이썬에 붙어 있는지
python3 -m pip --version

find_spec이 None을 반환하면 그 파이썬에는 실제로 없습니다. 설치가 아니라 위치의 문제입니다.

해결

• 가상환경을 쓰는 프로젝트라면 활성화 후 다시 실행합니다.

source .venv/bin/activate   # 윈도우: .venv\Scripts\activate
python -m pip install requests
python myscript.py

• 가상환경을 쓰지 않는다면, 확인한 그 파이썬으로 직접 설치합니다.

python3 -m pip install requests

• pip가 아예 없다면 python3 -m ensurepip --upgrade로 준비하거나, Debian/Ubuntu는 sudo apt install python3-pip python3-venv를 씁니다.

피해야 할 습관

• sudo pip install : 시스템 Python을 훼손할 수 있어 비추천. 가상환경을 씁니다.
• 오류가 나면 무조건 재설치 : 원인 확인(위 진단 3줄)이 재설치보다 빠릅니다.
• 가상환경을 프로젝트마다 만들지 않고 하나를 공유 : 프로젝트 간 버전 충돌의 원인이 됩니다.

관련 상황

• Docker 안에서 같은 오류가 나면 이미지에 패키지가 설치되지 않았거나, 설치와 실행 단계에서 사용한 파이썬이 다른 경우입니다. 빌드 로그에서 pip install이 실제로 수행됐는지 확인하세요.
• FastAPI 등 프레임워크 시작 직후 이 오류가 나면 위 "환경 불일치" 경우가 많습니다.

검증일은 자료의 최신성을 나타냅니다. 오래된 자료는 적용 조건을 확인하세요.