pip install pandas 했다. 분명히 잘 됐다. 근데 코드 실행하면 이 에러가 난다.
ModuleNotFoundError: No module named 'pandas'
이걸 처음 보는 사람은 당황하고, 두 번 이상 본 사람은 원인을 알면서도 순간 헷갈린다. 이 에러는 "모듈이 없다"는 게 아니라 "네가 실행하는 Python이 설치된 곳을 못 찾는다"는 뜻이다. 패턴별로 원인과 해결을 정리한다.
핵심 원인: pip와 python이 같은 환경을 보고 있지 않다
이 에러의 90%는 여기서 나온다. 시스템에 Python이 여러 개 있거나, 가상환경이 활성화되지 않은 상태에서 설치하면 발생한다.
먼저 어떤 Python, 어떤 pip를 쓰는지 확인한다:
# 현재 사용 중인 Python 경로 확인
which python
which python3
python --version
# 현재 사용 중인 pip 경로 확인
which pip
which pip3
# pip가 어디에 설치하는지 확인
pip show pandas
pip show pandas를 했는데 나오면 설치는 된 것이다. 근데 python이 다른 경로면 서로 다른 환경이다.
해결 1: python -m pip 를 쓴다 (가장 확실한 방법)
# ❌ 이렇게 쓰면 pip가 어떤 Python에 연결됐는지 불확실
pip install pandas
# ✅ 이렇게 쓰면 실행하는 Python과 100% 같은 환경에 설치
python -m pip install pandas
python3 -m pip install pandas
python -m pip는 현재 실행 중인 Python 인터프리터에 pip를 직접 연결한다. 이 방법이 가장 확실하다.
해결 2: 가상환경 활성화 확인
가상환경(venv)을 쓰면 activate가 되어 있어야 한다. 안 된 상태에서 설치하면 시스템 Python에 설치되고, 가상환경 Python은 못 찾는다.
# 가상환경 생성
python -m venv venv
# 활성화 — macOS/Linux
source venv/bin/activate
# 활성화 — Windows
venv\Scripts\activate
# 활성화 확인 (앞에 (venv) 표시 나옴)
# (venv) user@machine:~$
# 활성화된 상태에서 설치
pip install pandas
# 비활성화
deactivate
IDE(VS Code, PyCharm)를 쓰면 인터프리터 설정도 확인한다.
- VS Code:
Ctrl+Shift+P→Python: Select Interpreter→ 가상환경 경로 선택 - PyCharm:
Settings→Project→Python Interpreter→ 가상환경 선택
해결 3: PyPI 패키지명과 import명이 다른 경우
설치는 됐는데 이름이 달라서 못 찾는 케이스다. 대표적인 예시들:
# 설치명 → import명 (다른 경우)
pip install Pillow # import PIL
pip install opencv-python # import cv2
pip install scikit-learn # import sklearn
pip install python-dotenv # import dotenv
pip install beautifulsoup4 # import bs4
pip install pyyaml # import yaml
# ❌ 잘못 쓰는 경우
import Pillow # ModuleNotFoundError
# ✅ 맞는 import
import PIL
from PIL import Image
해결 4: Python 버전이 여러 개인 환경 (pyenv, conda 등)
# 현재 활성 Python 버전 확인
pyenv version
# 프로젝트 디렉토리에서 로컬 버전 설정
pyenv local 3.11.8
# 해당 버전으로 설치
python -m pip install pandas
conda를 쓰는 경우:
# conda 환경 목록
conda env list
# 환경 활성화
conda activate myenv
# 해당 환경에 설치 (conda 우선, pip는 없을 때만)
conda install pandas
# 또는
pip install pandas
해결 5: 같은 이름의 .py 파일이 있는 경우
프로젝트 폴더에 numpy.py, random.py 같이 표준 라이브러리나 패키지와 같은 이름의 파일을 만들면 충돌한다.
my_project/
├── main.py
├── numpy.py ← ❌ 이게 문제 (패키지보다 먼저 import됨)
└── utils.py
# main.py에서
import numpy # 실제 numpy가 아닌 my_project/numpy.py를 로드 → 에러
파일명을 바꿔야 한다. 표준 라이브러리나 외부 패키지와 이름이 겹치지 않도록 한다.
해결 6: __init__.py 누락 (직접 만든 패키지)
my_project/
├── main.py
└── utils/
├── helper.py ← 있음
└── __init__.py ← ❌ 없으면 에러
# __init__.py 생성 (내용은 비워도 됨)
touch utils/__init__.py
진단 체크리스트
| 상황 | 확인 명령어 | 해결 |
|---|---|---|
| 설치가 됐는지 모르겠다 | pip show 패키지명 |
없으면 python -m pip install |
| 설치됐는데 못 찾는다 | which python vs which pip |
python -m pip install 사용 |
| 가상환경 쓰는데 에러 | which python이 venv 경로인지 |
source venv/bin/activate |
| IDE에서만 에러 | IDE 인터프리터 설정 | 가상환경 Python 경로로 변경 |
| 설치명 헷갈린다 | PyPI에서 패키지 검색 | import명 확인 후 설치 |
| 직접 만든 모듈 에러 | 디렉토리에 __init__.py 있는지 | touch 패키지디렉토리/__init__.py |
빠른 진단 스크립트
어디에 설치됐는지 한 번에 보고 싶을 때:
import sys
print("Python 실행 경로:", sys.executable)
print("Python 버전:", sys.version)
print("\nPATH 목록:")
for path in sys.path:
print(" -", path)
이걸 실행해서 나오는 경로들을 확인한다. 내가 설치한 경로가 sys.path에 없으면 Python이 찾을 수가 없다.
정리
ModuleNotFoundError는 모듈 자체가 없는 게 아니라 현재 Python이 보는 경로에 없는 것이다. 순서대로 확인하면 빠르게 해결된다:
python -m pip install 패키지명으로 설치 — pip와 python 경로 일치 보장- 가상환경 활성화 여부 확인 (
which python이 venv 경로인지) - 패키지명과 import명이 다른 경우 확인 (Pillow→PIL, opencv-python→cv2 등)
- 같은 이름의 .py 파일 충돌 여부 확인
- 직접 만든 패키지라면
__init__.py누락 확인
python -m pip install을 습관화하면 1~2번 문제는 거의 안 만난다.
