Python ModuleNotFoundError: 설치했는데 모듈을 찾지 못할 때 확인 순서

짧은 요약

pip가 가리키는 Python과 실제 스크립트를 실행하는 Python이 다르면 설치 성공 메시지가 있어도 모듈을 찾지 못합니다. python -m pip 형식으로 같은 인터프리터에 설치하세요.

증상과 환경

ModuleNotFoundError: No module named 'requests'

전역 Python과 프로젝트 가상환경이 섞였거나 IDE가 다른 인터프리터를 선택했을 때 흔합니다.

원인

셸의 pip 실행 파일, python 실행 파일, IDE의 실행 인터프리터가 서로 다른 환경을 가리킵니다. 프로젝트 내부 파일 이름이 패키지 이름과 겹쳐 import 경로를 가리는 경우도 있습니다.

재현 예시

python -m venv .venv
# 가상환경을 활성화하지 않은 채 전역 pip에 설치
pip install requests
.venv/bin/python app.py

Windows에서는 마지막 경로가 .venv\Scripts\python.exe입니다.

단계별 해결법

1. 실제 Python 경로 확인

python -c "import sys; print(sys.executable); print(sys.path)"
python -m pip --version

두 출력의 Python 경로가 같은 환경인지 확인합니다.

2. 가상환경 활성화

.\.venv\Scripts\Activate.ps1

source .venv/bin/activate

3. 같은 인터프리터로 설치

python -m pip install --upgrade pip
python -m pip install requests
python -m pip show requests

4. 이름 충돌 확인

프로젝트에 requests.py, json.py, typing.py처럼 표준 라이브러리나 패키지와 같은 파일 이름이 있다면 바꾸고 생성된 캐시도 확인합니다.

확인법

python -c "import requests; print(requests.__file__)"

경로가 현재 가상환경 내부를 가리키면 정상입니다. IDE에서도 같은 인터프리터를 선택한 뒤 새 터미널을 여세요.

주의사항

권한 오류를 피하려고 무조건 관리자 권한이나 sudo pip를 사용하지 마세요. 시스템 Python을 손상시킬 수 있습니다.

관련 이슈

• requirements.txt와 잠금 파일 불일치
• Jupyter 커널과 셸 가상환경 차이
• 패키지명과 import 이름이 다른 라이브러리