이번 포스트에스는 [Python] 파이썬 ModuleNotFoundError, No module named 해결법에 대해 알아보려고 합니다.
파이썬 개발을 하다 보면 누구나 한 번쯤은 마주치게 되는 에러가 있습니다. 바로 ModuleNotFoundError: No module named 'xxx'인데요. 이 에러가 왜 발생하는지, 그리고 어떻게 해결할 수 있는지 차근차근 알아보겠습니다.
ModuleNotFoundError란?
ModuleNotFoundError는 파이썬이 코드에서 import하려는 모듈을 찾을 수 없을 때 발생하는 에러입니다. 파이썬은 다음 순서로 모듈을 찾습니다:
| 탐색 순서 | 위치 | 설명 |
|---|---|---|
| 1단계 | 현재 스크립트 디렉터리 | 실행 중인 .py 파일과 같은 폴더 |
| 2단계 | PYTHONPATH 환경변수 | 사용자가 설정한 추가 경로 |
| 3단계 | Python 표준 라이브러리 | os, sys 등 기본 제공 모듈 |
| 4단계 | site-packages | pip로 설치한 서드파티 패키지 |
어느 단계에서도 모듈을 찾지 못하면 ModuleNotFoundError가 발생합니다.
원인1: 모듈이 설치되지 않은 경우
원인
가장 흔한 원인으로, 필요한 서드파티 라이브러리가 시스템에 설치되지 않은 경우입니다.
import pandas # pandas가 설치되지 않은 경우
# ModuleNotFoundError: No module named 'pandas'
해결법
1단계: 설치 여부 확인
pip list | grep pandas
# 또는
pip show pandas
2단계: 모듈 설치
# 기본 설치
pip install pandas
# 특정 버전 설치
pip install pandas==1.5.3
# 여러 모듈 한번에 설치
pip install pandas numpy matplotlib
3단계: 설치 확인
import pandas as pd
print(pd.__version__) # 버전 출력되면 성공
원인2: 가상환경 문제
원인
가상환경을 사용할 때 발생하는 가장 흔한 문제들:
- 가상환경이 활성화되지 않은 상태에서 모듈 설치
- 전역에는 설치했지만 가상환경에는 설치하지 않음
- 잘못된 가상환경에서 코드 실행
해결법
1단계: 가상환경 생성 및 활성화
Windows:
# 가상환경 생성
python -m venv myenv
# 가상환경 활성화
myenv\Scripts\activate
# 활성화 확인 (터미널에 (myenv) 표시)
macOS/Linux:
# 가상환경 생성
python3 -m venv myenv
# 가상환경 활성화
source myenv/bin/activate
# 활성화 확인
2단계: 올바른 Python/pip 사용 확인
# 현재 사용 중인 python 확인
which python
# 결과: ./myenv/bin/python (가상환경 경로여야 함)
# 현재 사용 중인 pip 확인
which pip
# 결과: ./myenv/bin/pip (가상환경 경로여야 함)
3단계: 가상환경에서 모듈 설치
# 가상환경이 활성화된 상태에서
pip install 필요한모듈명
원인3: 모듈 경로 문제
원인
사용자가 직접 만든 모듈이나 프로젝트 내 다른 폴더의 모듈을 import할 때, 해당 경로가 Python의 모듈 탐색 경로에 포함되지 않은 경우입니다.
my_project/
├── main.py
├── utils/
│ └── helper.py
└── data/
└── processor.py
# main.py에서 다음 import 시 에러 발생
from utils.helper import some_function
# ModuleNotFoundError: No module named 'utils'
해결법
방법 1: sys.path에 경로 추가
import sys
import os
# 프로젝트 루트 디렉터리를 경로에 추가
project_root = os.path.dirname(os.path.abspath(__file__))
sys.path.append(project_root)
# 이제 import 가능
from utils.helper import some_function
방법 2: pathlib를 활용한 동적 경로 설정
from pathlib import Path
import sys
# 현재 파일 기준으로 프로젝트 루트 찾기
project_root = Path(__file__).parent
sys.path.append(str(project_root))
from utils.helper import some_function
방법 3: PYTHONPATH 환경변수 설정
Windows:
set PYTHONPATH=%PYTHONPATH%;C:\path\to\your\project
macOS/Linux:
export PYTHONPATH="${PYTHONPATH}:/path/to/your/project"
원인4: 모듈명 오타 및 대소문자 문제
원인
파이썬은 대소문자를 구분하므로, 모듈명의 작은 차이도 에러를 발생시킵니다.
# 잘못된 예시들
import numpY # numpy의 대소문자 실수
import reqeusts # requests의 오타
import matplotlob # matplotlib의 오타
해결법
1단계: 정확한 모듈명 확인
- PyPI 공식 사이트에서 정확한 패키지명 확인
- 공식 문서의 import 예제 참조
2단계: IDE 자동완성 활용
# IDE에서 'pan'까지만 타이핑하고 자동완성 사용
import pandas # 자동완성으로 정확한 명칭 확인
3단계: 설치된 패키지 목록에서 확인
pip list | grep -i pandas # 대소문자 구분없이 검색
원인5: Python 버전 호환성 문제
원인
- Python 2와 Python 3 환경이 혼재하는 경우
- 모듈이 특정 Python 버전에서만 지원되는 경우
- 시스템에 여러 Python 버전이 설치된 경우
해결법
1단계: 현재 Python 버전 확인
python --version
python3 --version
2단계: 올바른 pip 사용
# Python 3 사용 시
python3 -m pip install 모듈명
# 특정 Python 버전 지정
/usr/bin/python3.9 -m pip install 모듈명
3단계: 코드에서 Python 버전 확인
import sys
print(f"Python 버전: {sys.version}")
print(f"실행 파일 경로: {sys.executable}")
원인6: Jupyter Notebook에서의 특별한 경우
원인
Jupyter Notebook의 커널과 터미널의 Python 환경이 다른 경우 발생합니다.
해결법
방법 1: Notebook 내에서 직접 설치
# Jupyter 셀에서 실행
!pip install pandas
# 또는 시스템 Python 사용
import sys
!{sys.executable} -m pip install pandas
방법 2: 올바른 커널 설정
# 가상환경에 ipykernel 설치
pip install ipykernel
# Jupyter에 가상환경 커널 등록
python -m ipykernel install --user --name=myenv
파이썬 ModuleNotFoundError, No module named 오류 예방법은?
requirements.txt 활용
프로젝트의 모든 의존성을 명시해두면 환경 재구성이 쉬워집니다.
# requirements.txt
pandas==1.5.3
numpy>=1.21.0
matplotlib>=3.5.0
requests==2.28.2
설치 방법:
pip install -r requirements.txt
프로젝트 구조 최적화
my_project/
├── src/
│ ├── __init__.py # 패키지로 인식되도록
│ ├── main.py
│ └── utils/
│ ├── __init__.py # 서브패키지로 인식되도록
│ └── helper.py
├── tests/
├── requirements.txt
└── setup.py
setup.py를 통한 개발 설치
# setup.py
from setuptools import setup, find_packages
setup(
name="my_project",
packages=find_packages(),
install_requires=[
"pandas>=1.5.0",
"numpy>=1.21.0",
],
)
설치:
pip install -e . # 개발 모드로 설치
ModuleNotFoundError는 처음에는 복잡해 보이지만, 체계적으로 접근하면 쉽게 해결할 수 있습니다. 가상환경을 올바르게 사용하고, 모듈 설치를 정확히 확인하는 것이 가장 중요합니다. 이 포스트가 도움이 되셨으면 합니다. 🙂