ModuleNotFoundError: No module named 오류, pip로 설치했는데도 뜰 때 원인별 해결

파이썬 파일을 실행했는데 ModuleNotFoundError: No module named 'requests' 같은 메시지가 뜨고 멈춥니다.
분명히 pip install을 했는데도 똑같이 나오는 경우가 더 많습니다.
이 글은 윈도우에서 이 오류가 뜨는 원인을 5가지로 나눠, 메시지와 상황별로 해결하는 방법만 다룹니다.

(윈도우 11도 명령어는 같습니다.)

 

 

 

실제 오류 메시지

Traceback (most recent call last):
  File "C:\Users\사용자\test.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

 

작은따옴표 안의 이름이 파이썬이 찾지 못한 모듈입니다. 아래 예시의 requests 자리에 내 화면에 나온 이름을 넣어서 따라 하면 됩니다.

파이썬 실행 시 ModuleNotFoundError No module named requests 오류가 표시된 터미널 화면

 

 

 

 

30초 점검: 설치 여부와 설치 위치 확인하기

 

명령 프롬프트(cmd)를 열고 아래 두 줄을 차례로 입력합니다

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

 

첫 줄에서 "WARNING: Package(s) not found" 가 나오면 설치가 안 된 것입니다. → 원인 1
Name, Version, Location 이 나오는데도 오류가 난다면 설치는 됐지만 다른 파이썬으로 실행하고 있는 것입니다. → 원인 2, 3, 4
둘째 줄은 지금 실행되는 python.exe 의 경로입니다. 뒤에서 비교할 때 쓰니 적어 두세요.

pip show 결과와 현재 실행 중인 파이썬 경로가 출력된 명령 프롬프트 화면

 

 

 

 

원인별 해결 방법

 

원인 1. 패키지가 설치되지 않았을 때

아래 명령어로 설치합니다.

python -m pip install requests

pip install 대신 python -m pip install을 쓰는 이유는, 지금 python 명령으로 실행되는 바로 그 파이썬에 설치되기 때문입니다.
설치 도중 빨간 오류가 나오면 이 글이 아니라 "pip install 오류" 글의 범위입니다.

 

 

 

원인 2. 파이썬이 2개 이상 설치되어 있을 때

pip는 3.11에 설치했는데 실행은 3.12로 하는 경우입니다. 설치된 파이썬 목록은 아래 명령어로 봅니다.

py -0p

 

 

목록이 2줄 이상이면 실행할 버전을 정하고, 그 버전을 지정해서 설치합니다.

py -3.12 -m pip install requests
py -3.12 test.py

 

 

 

 

원인 3. VS Code가 다른 인터프리터를 쓰고 있을 때

터미널에서는 되는데 VS Code의 실행 버튼(▷)으로만 오류가 난다면 이 경우입니다.

1) Ctrl + Shift + P를 누르고 Python: Select Interpreter(한글 표시: Python: 인터프리터 선택) 를 입력합니다.
2) 목록에서 30초 점검의 둘째 줄에 나온 경로와 같은 항목을 고릅니다.
3) 열려 있던 터미널을 휴지통 아이콘으로 닫고 새로 엽니다.

선택된 인터프리터는 VS Code 오른쪽 아래 상태 표시줄에서 확인할 수 있습니다.

VS Code 인터프리터 선택 목록에 여러 파이썬 경로가 표시된 화면

 

 

 

 

원인 4. 가상환경을 켜지 않고 실행했을 때

프로젝트 폴더에 .venv나 venv 폴더가 있다면 패키지는 그 안에 설치되어 있습니다. 가상환경을 켠 뒤 실행하세요.

.venv\Scripts\activate

 

줄 맨 앞에 (.venv)가 붙으면 켜진 것입니다.
PowerShell에서 "이 시스템에서 스크립트를 실행할 수 없으므로" 가 뜨면 실행 정책 문제이니 "PowerShell 스크립트 실행 오류" 글을 먼저 보세요.

 

 

 

원인 5. 설치 이름과 import 이름이 다를 때

오류에 나온 이름 그대로 pip install 을 하면 "No matching distribution found" 가 나오는 패키지가 있습니다.

import cv2 → python -m pip install opencv-python
import PIL → python -m pip install Pillow
import sklearn → python -m pip install scikit-learn
import bs4 → python -m pip install beautifulsoup4
import yaml → python -m pip install PyYAML
import dotenv → python -m pip install python-dotenv

 

***

주의!!!

이름을 짐작해서 설치하지 마세요.

비슷한 이름으로 올라온 악성 패키지 사례가 있습니다.

그 라이브러리의 공식 문서나 pypi.org에서 설치 이름을 확인한 뒤 설치합니다.

***

 

 

 

그 외. "is not a package" 가 같이 나올 때

ModuleNotFoundError: No module named 'requests.adapters'; 'requests' is not a package

 

끝에 is not a package 가 붙으면 설치 문제가 아닙니다. 

내 폴더에 requests.py 처럼 모듈과 같은 이름의 파일이 있어서 파이썬이 그 파일을 먼저 불러온 것입니다.
파일 이름을 my_requests.py 처럼 바꾸고, 같은 폴더에 생긴 __pycache__ 폴더도 지운 뒤 다시 실행합니다.

 

 

 

 

 

해결됐는지 확인하는 방법

 

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

 

오류 없이 버전 숫자가 나오면 해결된 것입니다.

VS Code에서는 실행 버튼(▷)으로도 한 번 더 실행해 보세요.

 

 

 

 

그래도 안 될 때

 

python 명령 자체가 "내부 또는 외부 명령 ... 이 아닙니다" 로 나오면 모듈이 아니라 PATH 문제입니다.

"python 내부 외부 명령 오류" 글에서 다룹니다.
회사 PC에서 설치가 계속 막히면 프록시나 보안 프로그램이 원인일 수 있습니다. 

이때는 "pip install 오류" 글의 순서대로 확인하세요.

 

 

 

 

한 줄 정리

 

python -m pip show 로 설치 여부 확인 

→ python -m pip install 로 설치 

→ 그래도 뜨면 실행하는 파이썬(py -0p, VS Code 인터프리터, 가상환경)이 설치한 파이썬과 같은지 확인