파이썬 ModuleNotFoundError 완벽 해결법: requests 설치부터 가상환경 함정까지

파이썬으로 외부 API를 호출하려고 import requests를 적었는데, 실행하자마자 ModuleNotFoundError: No module named 'requests'가 콘솔을 빨갛게 물들인 경험은 누구에게나 있습니다. 분명히 pip install requests를 돌렸는데도 같은 에러가 반복되면 답답함은 배가 됩니다. 이 글에서는 단순한 "pip install 하세요" 수준을 넘어, 왜 이 에러가 나는지 원인을 분류하고, 어느 단계에서 무엇이 어긋났는지 진단하는 절차까지 정리합니다.

1. ModuleNotFoundError가 의미하는 것

이 예외는 ImportError의 하위 클래스로, 파이썬 인터프리터가 임포트하려는 모듈을 검색 경로(sys.path) 어디에서도 찾지 못했을 때 발생합니다. 핵심은 "설치를 안 했다"가 아니라 "지금 실행 중인 이 인터프리터가 그 모듈을 못 본다"입니다. 이 미묘한 차이를 이해하면 해결의 절반은 끝난 셈입니다.

즉, 모듈이 시스템 어딘가에 분명히 깔려 있어도, 지금 코드를 돌리는 파이썬이 그 위치를 모르면 동일한 에러가 납니다. 대부분의 "설치했는데 안 돼요" 사연이 바로 여기서 발생합니다.

---

2. 원인 4가지로 나눠 보기

구분	증상	한 줄 설명
① 미설치	어디서도 안 보임	패키지를 실제로 설치한 적이 없음
② 오타·대소문자	비슷한 이름	Requests, request처럼 이름이 틀림
③ 환경 불일치	한 곳에선 되는데 한 곳에선 안 됨	설치한 파이썬과 실행하는 파이썬이 다름
④ pip↔python 불일치	pip list엔 있는데 import 실패	pip와 python이 서로 다른 인터프리터를 가리킴

실무에서 가장 골치 아픈 건 ③번과 ④번입니다. 여러 버전의 파이썬이 깔린 macOS·리눅스나, 가상환경을 쓰면서 활성화를 깜빡한 경우가 대표적입니다.

---

3. 단계별 진단 및 해결

아래 순서대로 따라가면 어느 단계에서 어긋났는지 좁혀갈 수 있습니다.

1단계 — 모듈 이름부터 확인

파이썬은 대소문자를 구분합니다. 패키지 이름은 전부 소문자 requests입니다. Requests나 request(단수형)는 다른 이름이거나 존재하지 않는 패키지입니다.

# 잘못된 예 (단수형, 대문자)
import Request   # ModuleNotFoundError
# 올바른 예
import requests

2단계 — 지금 쓰는 파이썬이 무엇인지 확인

이게 핵심입니다. pip만 믿지 말고, 코드를 실행하는 그 인터프리터로 직접 설치하세요.

# 실행에 쓰는 파이썬 경로 확인
which python3        # macOS / Linux
where python         # Windows

# 그 파이썬에 묶인 pip로 설치 (가장 안전한 방법)
python3 -m pip install requests

python3 -m pip 방식은 "지금 이 파이썬이 사용하는 pip"를 명시적으로 호출하므로, pip↔python 불일치(④번 원인)를 근본적으로 차단합니다.

3단계 — 설치 여부와 위치 확인

# 설치된 패키지 목록에서 requests 검색
python3 -m pip show requests

show 명령은 설치 버전과 함께 Location: 항목으로 어느 디렉터리에 깔렸는지까지 알려줍니다. 이 경로가 실행 환경의 site-packages와 일치하는지 보는 것이 진단의 핵심입니다.

4단계 — 가상환경 활성화 상태 점검

프로젝트별 가상환경(venv)을 쓴다면, 활성화한 상태에서 설치하고 실행해야 합니다.

# 가상환경 생성
python3 -m venv .venv

# 활성화
source .venv/bin/activate     # macOS / Linux
.venv\Scripts\activate        # Windows (PowerShell/CMD)

# 활성화된 상태에서 설치
pip install requests

활성화에 성공하면 프롬프트 앞에 (.venv)가 붙습니다. 이 표시가 없는 상태에서 설치하면 시스템 전역에 깔려 환경이 꼬이기 쉽습니다.

5단계 — 코드에서 직접 경로 확인 (최후의 디버깅)

그래도 안 되면, 파이썬 안에서 실제 검색 경로를 출력해 봅니다.

import sys
# 현재 인터프리터가 모듈을 찾는 경로 목록
for path in sys.path:
    print(path)
# 실행 중인 파이썬 실행 파일 위치
print(sys.executable)

여기서 출력된 sys.executable이 2단계의 which python3 결과와 다르다면, 에디터(IDE)가 엉뚱한 인터프리터를 쓰고 있는 것입니다. VS Code라면 우측 하단 또는 명령 팔레트의 "Python: Select Interpreter"에서 가상환경 인터프리터를 선택하세요.

---

4. requests 실전 사용법

설치가 끝났으면 실제로 써봅니다. requests는 표준 라이브러리 urllib보다 직관적이라 가장 널리 쓰이는 HTTP 클라이언트입니다.

GET 요청 — 데이터 가져오기

import requests

# 예시 엔드포인트 (실제 사용 시 본인 API 주소로 교체)
endpoint = "https://api.example.com/users"

try:
    res = requests.get(endpoint, timeout=5)  # timeout으로 무한 대기 방지
    res.raise_for_status()                   # 4xx/5xx면 예외 발생
    payload = res.json()                     # 응답 본문을 dict로 파싱
    print(payload)

except requests.exceptions.HTTPError as e:
    print(f"HTTP 상태 에러: {e}")
except requests.exceptions.Timeout:
    print("요청이 시간 초과되었습니다.")
except requests.exceptions.RequestException as e:
    print(f"요청 처리 중 오류: {e}")

raise_for_status()는 404나 500 같은 응답을 받았을 때 조용히 넘어가지 않고 예외로 바꿔주는 안전장치입니다. timeout을 반드시 지정하는 습관도 중요합니다. 지정하지 않으면 서버가 응답하지 않을 때 프로그램이 영원히 멈출 수 있습니다.

POST 요청 — 데이터 보내기

import requests

endpoint = "https://api.example.com/posts"
body = {"title": "테스트 글", "author": "editor"}

try:
    res = requests.post(endpoint, json=body, timeout=5)  # json= 로 보내면 헤더 자동 설정
    res.raise_for_status()
    created = res.json()
    print(f"생성된 리소스 ID: {created.get('id')}")

except requests.exceptions.RequestException as e:
    print(f"전송 실패: {e}")

data= 대신 json= 인자를 쓰면 requests가 본문을 자동으로 JSON 직렬화하고 Content-Type: application/json 헤더까지 붙여줍니다. REST API와 통신할 때 가장 흔히 쓰는 형태입니다.

---

5. 자주 빠지는 함정과 엣지케이스

• VS Code 인터프리터 미스매치: 터미널에선 되는데 "Run" 버튼으로는 에러가 난다면 십중팔구 IDE가 다른 인터프리터를 쓰는 경우입니다. 5단계의 sys.executable로 확인하세요.
• pip가 파이썬2를 가리킴: 오래된 시스템에서 pip가 파이썬2용일 수 있습니다. 항상 python3 -m pip를 쓰면 안전합니다.
• sudo로 전역 설치한 뒤 권한 꼬임: sudo pip install은 가급적 피하고 가상환경을 쓰세요. 시스템 패키지와 충돌하면 복구가 어렵습니다.
• 파일명을 requests.py로 지음: 본인이 만든 스크립트 이름이 requests.py면, 파이썬이 진짜 라이브러리 대신 그 파일을 임포트해 엉뚱한 에러가 납니다. 표준 라이브러리·유명 패키지와 같은 파일명은 피하세요.
• 주피터 노트북 커널 불일치: 노트북에서 안 될 땐 !python -m pip install requests처럼 노트북 커널의 파이썬으로 직접 설치하는 것이 확실합니다.

---

6. 요약 체크리스트

1. 이름이 정확히 requests(소문자)인가
2. python3 -m pip install requests로 실행 파이썬에 직접 설치했는가
3. python3 -m pip show requests로 설치 위치를 확인했는가
4. 가상환경을 쓴다면 활성화 상태((.venv) 표시)에서 설치·실행했는가
5. IDE의 인터프리터가 그 가상환경을 가리키는가 (sys.executable 확인)

ModuleNotFoundError는 "설치 실패"보다 "환경 불일치"인 경우가 압도적으로 많습니다. 설치 명령을 한 번 더 치기 전에, 지금 실행하는 파이썬이 무엇인지부터 확인하는 습관을 들이면 같은 에러로 시간을 낭비할 일이 크게 줄어듭니다.

---

AI에게 물어볼 때 (프롬프트 팁)

이런 환경 문제는 ChatGPT나 Claude 같은 AI에게 물으면 빠르게 좁힐 수 있습니다. 단, 막연히 "에러 나요"라고 묻지 말고 환경 정보를 함께 주는 것이 핵심입니다. Prompt Architect가 권장하는 프롬프트 예시를 소개합니다.

예시 1 — 진단을 맡기는 프롬프트

역할: 파이썬 환경 디버깅 전문가.
상황: import requests에서 ModuleNotFoundError 발생.
환경: macOS, python3 -m pip install requests는 성공, 그런데 VS Code 실행 시에만 에러.
요청: 원인을 가능성 높은 순으로 나열하고, 각 가설을 확인하는 명령어를 함께 알려줘.

예시 2 — 진단 명령 출력을 붙여 검증하는 프롬프트

아래는 내 환경 출력이야:
- which python3: /usr/bin/python3
- sys.executable: /Users/me/proj/.venv/bin/python
이 둘이 다른데, 무엇이 문제이고 어떻게 일치시키는지 단계별로 알려줘.

예시 3 — 재발 방지 루틴을 요청하는 프롬프트

앞으로 파이썬 프로젝트에서 ModuleNotFoundError를 예방하려고 해.
venv 생성부터 의존성 고정(requirements.txt)까지 표준 워크플로우를
명령어 체크리스트 형태로 정리해줘.

이처럼 역할·상황·환경·요청을 구조화해 질문하면 AI가 추측 대신 정확한 진단을 내놓습니다. 더 정교한 프롬프트 설계법은 Prompt Architect의 프롬프트 분석기로 점검해 보세요.