파이썬 ModuleNotFoundError 완벽 해결 가이드 - 라이브러리 인식 안 될 때 3가지 해결법

파이썬 “ModuleNotFoundError” 에러 3가지 해결 방법 총정리

파이썬을 시작하면서 가장 많이 만나는 에러가 뭘까요? 바로 ModuleNotFoundError예요! 😱

ModuleNotFoundError: No module named ‘requests’

“분명히 설치했는데 왜 안 되지?”, “어제까지 잘 됐는데 갑자기 왜 안 돼?” 이런 경험 있으시죠?

걱정 마세요! 이 에러는 원인이 딱 3가지밖에 없어요. 이 글에서 모든 경우를 완벽하게 해결하는 법을 알려드릴게요!

💡 시리즈 연결: 이전 글에서 pip install로 라이브러리를 설치하는 법을 배웠어요. 설치했는데도 에러가 난다면? 이 글을 읽어보세요!

ModuleNotFoundError가 뭔가요?

ModuleNotFoundError는 파이썬이 여러분이 import하려는 라이브러리(모듈)을 찾지 못했다는 뜻이에요.

ModuleNotFoundError 발생 과정

에러가 발생하는 3가지 원인

원인	설명	해결법
1. 미설치	라이브러리를 아예 설치 안 함	pip install로 설치
2. 잘못된 경로	다른 파이썬 버전에 설치됨	인터프리터 경로 확인
3. 가상환경 문제	다른 가상환경에 설치됨	올바른 가상환경 활성화

해결법 1: 라이브러리가 설치 안 되어 있음 (가장 흔한 원인)

제일 간단한 원인이에요. 그냥 설치를 안 했거나 잊어버린 거죠!

✅ 해결 방법

Step 1: 에러 메시지 확인

ModuleNotFoundError: No module named ‘requests’

→ requests가 없다는 뜻!

Step 2: pip install로 설치

$ pip install requests # 출력: Collecting requests Downloading requests-2.31.0-py3-none-any.whl Successfully installed requests-2.31.0 ✅

Step 3: 다시 실행

import requests
print(“성공! 이제 잘 작동해요!”)
    

🔍 설치 여부 확인하는 법

# 방법 1: pip list로 확인 $ pip list | grep requests requests 2.31.0 # 방법 2: pip show로 상세 확인 $ pip show requests Name: requests Version: 2.31.0 Location: C:\Python312\Lib\site-packages # 방법 3: 파이썬에서 직접 확인 $ python -c “import requests; print(‘설치됨!’)”

해결법 2: 잘못된 파이썬 경로 (두 번째로 흔한 원인)

이게 제일 헷갈려요! 파이썬이 여러 개 설치되어 있으면 엉뚱한 곳에 라이브러리가 설치될 수 있어요.

다른 파이썬 버전에 설치된 경우

✅ 해결 방법

Step 1: 현재 사용 중인 파이썬 확인

# Windows $ python –version Python 3.12.0 $ where python C:\Python312\python.exe C:\Python311\python.exe # Mac/Linux $ python3 –version $ which python3

Step 2: 확실하게 설치하기

# 현재 실행 중인 파이썬에 설치 $ python -m pip install requests # 또는 python3 사용 $ python3 -m pip install requests

💡 왜 python -m pip일까요?
• pip install: 시스템의 기본 pip (어떤 파이썬인지 모호)
• python -m pip install: 현재 실행 중인 파이썬의 pip (확실!)

🎯 VS Code에서 인터프리터 설정하기

VS Code는 어떤 파이썬을 사용할지 선택할 수 있어요!

VS Code 인터프리터 설정법:

1 Ctrl + Shift + P (Mac: Cmd + Shift + P)

2 “Python: Select Interpreter” 입력

3 파이썬 버전 선택 (라이브러리가 설치된 버전!)

# 예시:
Python 3.12.0 (‘base’: conda) ← 이걸 선택!
Python 3.11.5 64-bit
    

4 VS Code 재시작 (권장)

해결법 3: 가상환경 문제 (초보자 헷갈림)

가상환경을 사용하면 프로젝트마다 독립된 공간이 생겨요. A 가상환경에 설치했는데 B 가상환경에서 실행하면 당연히 에러!

✅ 해결 방법

Step 1: 현재 활성화된 가상환경 확인

# Windows $ where python C:\project\venv\Scripts\python.exe ← 가상환경 # Mac/Linux $ which python3 /Users/user/project/venv/bin/python3 ← 가상환경

Step 2: 가상환경이 활성화되어 있는지 확인

# 터미널 앞에 (venv) 표시가 있으면 활성화됨 (venv) $ pip install requests ← 올바름 # 없으면 활성화 필요 $ pip install requests ← 잘못됨! (전역에 설치)

Step 3: 가상환경 활성화

# Windows $ venv\Scripts\activate # Mac/Linux $ source venv/bin/activate # 활성화 확인 (앞에 (venv) 표시됨) (venv) $

Step 4: 가상환경에 설치

(venv) $ pip install requests

🔄 가상환경 완전 재설정 (최후의 수단)

가상환경이 꼬였다면 아예 새로 만드는 게 빨라요!

# 1. 기존 가상환경 삭제 $ rmdir /s venv # Windows $ rm -rf venv # Mac/Linux # 2. 새로 생성 $ python -m venv venv # 3. 활성화 $ venv\Scripts\activate # Windows $ source venv/bin/activate # Mac/Linux # 4. 필요한 라이브러리 재설치 (venv) $ pip install -r requirements.txt

실전 케이스별 해결 시나리오

케이스 1: “분명히 설치했는데 안 돼요!”

증상:

$ pip install pandas Successfully installed pandas ✅ $ python test.py ModuleNotFoundError: No module named ‘pandas’ ❌

원인: pip와 python이 다른 버전! 해결:

$ python -m pip install pandas ← 확실한 방법

케이스 2: “어제까지 잘 됐는데 갑자기 안 돼요!”

증상:

# 어제는 잘 됐는데…
import requests
# ModuleNotFoundError!
    

원인: VS Code나 IDE의 인터프리터가 바뀜 해결:

VS Code: Ctrl + Shift + P → “Python: Select Interpreter”
가상환경 다시 활성화
터미널 재시작

케이스 3: “Jupyter Notebook에서만 안 돼요!”

증상:

# 터미널에서는 잘 되는데
$ python -c “import pandas”  # 성공

# Jupyter에서는 에러
import pandas  # ModuleNotFoundError!
    

원인: Jupyter가 다른 커널 사용 해결:

# 1. 가상환경 활성화 $ source venv/bin/activate # 2. ipykernel 설치 (venv) $ pip install ipykernel # 3. 커널 등록 (venv) $ python -m ipykernel install –user –name=venv # 4. Jupyter에서 Kernel → Change kernel → venv 선택

케이스 4: “PyCharm에서만 안 돼요!”

PyCharm 인터프리터 설정:

1 File → Settings (Mac: Preferences)

2 Project: [프로젝트명] → Python Interpreter

3 톱니바퀴 ⚙️ 클릭 → Add

4 가상환경 경로 선택 또는 새로 생성

5 OK → 인터프리터 변경 완료!

완벽한 해결 체크리스트

🔍 ModuleNotFoundError 해결 순서:

☑️ 1단계: 설치 여부 확인

$ pip list | grep [라이브러리명] $ pip show [라이브러리명]

☑️ 2단계: 파이썬 경로 확인

$ python –version $ where python # Windows $ which python3 # Mac/Linux

☑️ 3단계: 확실하게 설치

$ python -m pip install [라이브러리명]

☑️ 4단계: 가상환경 확인

# 활성화 여부 확인 $ echo $VIRTUAL_ENV # Mac/Linux $ echo %VIRTUAL_ENV% # Windows

☑️ 5단계: IDE/편집기 재시작

VS Code: 인터프리터 재선택
PyCharm: Invalidate Caches / Restart
Jupyter: Kernel 재시작

에러 예방법: 이렇게 하면 에러 안 나요!

1. 프로젝트마다 가상환경 사용

# 새 프로젝트 시작할 때마다 $ python -m venv venv $ source venv/bin/activate # 또는 venv\Scripts\activate $ pip install [필요한 라이브러리]

2. requirements.txt 작성

# 설치한 라이브러리 저장 $ pip freeze > requirements.txt # 다른 컴퓨터/가상환경에서 한 번에 설치 $ pip install -r requirements.txt

3. IDE 인터프리터 설정 확인

💡 프로젝트 시작 시 체크리스트:
✅ 가상환경 생성했나요?
✅ 가상환경 활성화했나요?
✅ IDE 인터프리터 설정 확인했나요?
✅ requirements.txt 작성했나요?

4. python -m pip 사용 습관화

# ❌ 애매함
pip install requests

# ✅ 확실함
python -m pip install requests

자주 묻는 질문 (FAQ)

Q1: pip install은 성공했는데도 에러가 나요!

A: 99% 경로 문제예요. python -m pip install 사용하세요!

Q2: 여러 파이썬 버전이 있는데 어떻게 관리하나요?

A: 프로젝트마다 가상환경을 만들어서 독립적으로 관리하세요!

# Python 3.11 프로젝트 $ python3.11 -m venv venv_311 $ source venv_311/bin/activate # Python 3.12 프로젝트 $ python3.12 -m venv venv_312 $ source venv_312/bin/activate