파이썬 ModuleNotFoundError / ImportError 해결 — No module named 잡는 법

증상: No module named 'X'

파이썬 실행 중 가장 흔한 에러입니다.

ModuleNotFoundError: No module named 'requests'
ImportError: cannot import name 'something' from 'module'

둘은 사촌입니다. ModuleNotFoundError는 "모듈 자체를 못 찾음"이고, ImportError는 "모듈은 찾았지만 그 안의 이름을 못 가져옴"입니다. (ModuleNotFoundError는 ImportError의 하위 종류입니다.)

왜 이 에러가 나는가

• 패키지 미설치 — pip install을 안 했거나 다른 환경에 설치됨. 가장 흔합니다.
• 가상환경 불일치 — venv를 활성화 안 하고 실행, 또는 잘못된 인터프리터.
• pip와 python 불일치 — pip install은 py2에, 실행은 py3에서.
• 모듈 경로/패키지 구조 문제 — 상대 import 실패, __init__.py 누락.
• 파일명 충돌 — 내 파일을 random.py로 만들어 표준 모듈을 가림.
• 순환 import — ImportError의 흔한 원인.

케이스별 해결

1) 설치부터 — 단, 같은 인터프리터로

핵심은 "실행하는 python과 같은 곳에 설치"입니다.

python -m pip install requests

pip install 대신 python -m pip를 쓰면 현재 python과 일치하는 pip가 보장됩니다. python3로 실행한다면 python3 -m pip ....

2) 가상환경 활성화 확인

# 생성
python -m venv venv
# 활성화
source venv/bin/activate      # macOS/Linux
venv\Scripts\activate         # Windows
# 어떤 python을 쓰는지 확인
which python   /  where python
pip list                      # 설치 목록 확인

3) 어디에 설치됐는지 추적

python -c "import sys; print(sys.executable)"
python -m pip show requests   # Location 확인

실행 인터프리터와 설치 위치가 다르면 그게 원인입니다. VS Code라면 우하단 인터프리터 선택을 venv로 맞추세요.

4) 파일명 충돌

내 스크립트 이름이 표준/외부 모듈과 같으면 그 모듈을 가립니다. 예: email.py, random.py. 파일명을 바꾸고 같은 폴더의 __pycache__를 지우세요.

5) ImportError: cannot import name

이름 철자, 그 객체가 실제 그 모듈에 있는지, 그리고 순환 import를 의심하세요. 두 모듈이 서로를 import하면 로딩 중 일부 이름이 아직 없을 수 있습니다. 공통 코드를 별도 모듈로 분리해 해결합니다.

6) 패키지 구조 / 상대 import

패키지로 인식되려면 폴더에 __init__.py가 필요할 수 있고, 상대 import(from .utils import x)는 모듈로 실행해야 합니다.

python -m mypackage.main      # 패키지 모드로 실행

원인별 비교

예방

• 프로젝트마다 가상환경(venv)을 따로 만드세요.
• 의존성은 requirements.txt(또는 poetry/pipenv)로 고정.
• pip보다 python -m pip 습관을 들이면 환경 불일치가 거의 사라집니다.
• 스크립트 이름을 표준 모듈명과 겹치지 않게 짓기.

자주 묻는 질문

Q1. 분명 pip install 했는데 No module named가 떠요.

설치된 환경과 실행 환경이 다릅니다. python -m pip install로 다시 깔고, python -c "import sys; print(sys.executable)"로 같은 인터프리터인지 확인하세요.

Q2. ModuleNotFoundError와 ImportError 차이가 뭔가요?

ModuleNotFoundError는 모듈을 아예 못 찾은 것, ImportError는 모듈은 있는데 그 안의 특정 이름을 못 가져온 것입니다. 전자는 설치/경로, 후자는 이름/순환 import를 의심하세요.

Q3. VS Code에서만 빨간 줄이 떠요.

에디터가 선택한 인터프리터가 venv가 아닐 가능성이 큽니다. 명령 팔레트에서 'Python: Select Interpreter'로 프로젝트 venv를 선택하세요.