ModuleNotFoundError·ImportError 5분 해결 — 원인별 진단표와 복붙 명령어

ModuleNotFoundError·ImportError 5분 해결 — 원인별 진단표와 복붙 명령어

파이썬 개발 가이드 2편 · 1편에서 환경은 만들었는데, 막상 python app.py 했더니 빨간 글씨가 뜬다면 이 글입니다.

"분명 pip install 했는데 왜 No module named가 뜨지?"

1편에서 venv를 만들고 패키지도 깔았습니다. 그런데 실행하면 이 메시지가 뜹니다.

ModuleNotFoundError: No module named 'requests'

설치를 했는데도 못 찾는 이유는 거의 항상 "설치한 파이썬"과 "실행하는 파이썬"이 다르기 때문입니다. 그리고 좋은 소식이 있습니다. 임포트 에러는 무한히 많아 보이지만, 실제 원인은 딱 7가지로 압축됩니다.

1. 완전히 설치 안 됨
2. 잘못된 인터프리터 / venv 미활성화
3. sys.path · PYTHONPATH 문제
4. 상대 import 오류
5. 패키지명 ≠ 임포트명
6. 순환 import
7. __init__.py 누락

이 글의 목표는 추측을 없애는 것입니다. 진단 명령어로 원인을 좁히고 → 표에서 원인을 찾고 → 복붙으로 해결하는 순서로 갑니다.

30초 진단 루틴: 원인을 좁히는 4개 명령어

막혔을 때 위에서부터 아래로 그대로 쳐 보세요. "어떤 파이썬이 어디 패키지를 보는지"가 30초 만에 드러납니다.

# 1) 지금 'python'이 실제로 어떤 실행파일인가
which python        # Windows: where python

# 2) 'pip'은 어느 파이썬에 붙어 있나
pip -V

# 3) 실행 중인 파이썬과 모듈 검색 경로 전체
python -c "import sys; print(sys.executable); print(sys.path)"

# 4) 그 파이썬에 실제로 깔린 패키지 목록
python -m pip list

각 줄을 어떻게 읽는지가 핵심입니다.

핵심 원칙 하나만 기억하세요. pip install이 아니라 python -m pip install을 쓰세요. 그래야 "지금 그 파이썬"에 정확히 설치됩니다. PEP에서도 python -m 실행을 권장 패턴으로 굳혀 왔습니다.

원인별 진단표와 복붙 해결책

위 진단 결과를 손에 들고, 아래 표에서 내 증상을 찾으세요.

실무 팁: 현업에서 터지는 임포트 에러의 대부분은 ②번(인터프리터 불일치) 하나로 수렴합니다. 특히 터미널에서는 잘 되는데 IDE에서만 깨지면 거의 확실합니다. 그러니 막히면 원인을 고민하기 전에 sys.executable부터 찍어 보세요.

자주 터지는 함정 3종 집중 공략

① IDE 인터프리터 불일치 (VSCode / PyCharm)

터미널에선 되는데 IDE 실행 버튼만 누르면 깨진다면, IDE가 venv가 아닌 다른 파이썬을 쓰고 있는 겁니다.

VSCode

1. Ctrl/Cmd + Shift + P → Python: Select Interpreter
2. 목록에서 프로젝트 venv 경로(./venv/bin/python) 선택
3. 고정하려면 .vscode/settings.json에 직접 명시:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python"
}

(스크린샷 캡션: VSCode 우측 하단 상태바에 선택된 인터프리터 경로가 venv를 가리키는지 확인)

PyCharm

1. Settings → Project → Python Interpreter
2. 톱니바퀴 → Add Interpreter → Add Local Interpreter
3. Existing 선택 후 venv/bin/python 지정

(스크린샷 캡션: Python Interpreter 드롭다운에 프로젝트 venv가 선택된 상태)

② 패키지명 ≠ 임포트명 대표 사례표

pip install로 치는 이름과 import로 부르는 이름이 다른 패키지들이 있습니다. 이걸 모르면 분명히 깔았는데 No module named가 뜹니다.

규칙: 하이픈은 임포트 시 언더스코어가 되거나 아예 다른 이름이 됩니다. 헷갈리면 python -m pip show pillow로 실제 패키지 정보를 확인하세요.

③ python script.py vs python -m package.module

상대 import(from . import utils) 에러의 99%는 실행 방식 때문입니다.

# ❌ 상대 import가 들어간 파일을 직접 실행하면 깨짐
python myapp/main.py
# → attempted relative import with no known parent package

# ✅ 패키지로 실행하면 부모 패키지 컨텍스트가 생겨 정상 동작
python -m myapp.main

-m으로 실행하면 파이썬이 해당 모듈을 "패키지의 일부"로 인식해 상대 import가 풀립니다.

2026 트렌드: Astral의 uv가 빠르게 표준으로 자리잡으며 uv pip install / uv run을 쓰는 팀이 늘었습니다. uv run python ...은 프로젝트 venv를 자동으로 잡아주기 때문에 ②번 불일치 문제 자체가 거의 사라집니다. Python 3.13에서도 프로젝트별 venv + python -m 실행 조합이 여전히 가장 안전한 기본값입니다.

결론: 진단표 1장으로 끝내기

막히면 순서는 항상 같습니다.

1. which python + pip -V 경로가 같은지 본다 → 다르면 venv 활성화
2. python -m pip list에 패키지가 있는지 본다 → 없으면 python -m pip install
3. 있는데도 안 되면 → 임포트명 사례표 + 상대 import(-m 실행) 확인

이 3단계만 위에서부터 따라 치면 임포트 에러는 5분 안에 풀립니다.

참고: 공식 문서

이 글에서 다루는 동작·설정·에러의 1차 출처는 다음 공식 문서입니다. 버전별 옵션과 정확한 동작은 여기서 확인하세요.

• Python 공식 문서

자주 묻는 질문 (FAQ)

Q. 터미널에선 되는데 주피터(.ipynb)에서만 No module named가 떠요. A. 노트북 커널이 다른 파이썬을 쓰고 있는 겁니다. 셀에서 import sys; print(sys.executable)로 커널 경로를 확인하세요. 노트북 안에서 !pip install을 쳐도 커널이 아닌 엉뚱한 파이썬에 설치될 수 있으니, 대신 %pip install X(매직 명령)를 쓰거나, venv를 커널로 등록하세요:

python -m ipykernel install --user --name=myvenv

그 후 주피터에서 myvenv 커널을 선택합니다.

Q. 도커 컨테이너에서만 모듈이 없습니다. A. 세 가지를 확인하세요. ① COPY requirements.txt → RUN pip install 순서가 맞는지(소스 전체보다 requirements를 먼저 복사해야 빌드 캐시가 잘 듭니다), ② 의존성을 바꿨는데 캐시 때문에 RUN pip install이 재실행 안 된 건 아닌지(docker build --no-cache로 검증), ③ base 이미지 파이썬 버전과 로컬 버전이 달라 호환 안 되는 휠이 깔린 건 아닌지. 컨테이너 안에서 python -m pip list로 실제 설치 여부를 직접 확인하는 게 가장 빠릅니다.

Q. pip install은 됐다는데 실행하면 없다고 합니다. A. user 영역(pip install --user)에 깔았는데 실행은 system 파이썬으로 하는 전형적 경우입니다. pip -V와 which python 경로를 비교하고, 항상 python -m pip install로 "지금 그 파이썬"에 설치하세요.

다음 편(3편)에서는 파이썬 디버깅 & 예외 처리 실전 — 트레이스백을 빠르게 읽는 법과 pdb/breakpoint() 활용법을 다룹니다.