[Python 파이썬] ModuleNotFoundError 오류 해결 방법

 

파이썬 개발을 하다 보면 가장 당혹스러운 순간 중 하나가 분명히 설치한 것 같은 라이브러리를 불러올 때 "ModuleNotFoundError: No module named '...'"라는 메시지를 마주하는 것입니다. 코드는 완벽해 보이는데 모듈을 찾을 수 없다는 에러는 초보자뿐만 아니라 숙련된 개발자에게도 종종 발생하는 문제입니다.

오늘은 이 오류가 발생하는 근본적인 원인부터, 가상환경 설정, 그리고 경로(Path) 문제까지 단계별 해결 방법을 상세히 정리해 보겠습니다.

 

---

1. ModuleNotFoundError 왜 발생하는 걸까?

이 에러의 핵심은 "파이썬 인터프리터가 해당 이름의 라이브러리나 파일을 찾을 수 있는 경로에 존재하지 않는다"는 것입니다. 단순히 설치를 안 한 경우도 있지만, 대부분은 '어디에' 설치했느냐의 문제입니다.

대표적인 발생 원인

• 라이브러리 미설치: pip install을 통해 패키지를 설치하지 않은 경우
• 환경 불일치: 패키지는 설치했지만, 현재 실행 중인 파이썬 환경(가상환경 등)과 다른 곳에 설치된 경우
• 오타: 모듈 이름을 잘못 입력한 경우 (대소문자 구분 필수)
• 경로 문제: 직접 만든 파일(모듈)을 불러올 때 폴더 구조가 시스템 경로에 포함되지 않은 경우

---

2. 단계별 해결 방법: 기본부터 심화까지

Step 1. 패키지 설치 여부와 이름 확인

가장 먼저 터미널(또는 CMD)에서 해당 패키지가 설치되어 있는지 확인해야 합니다. 설치가 안 되어 있다면 아래 명령어로 설치를 진행하세요.

# 패키지 설치 (예: pandas)
pip install pandas

# 설치된 목록 확인
pip list

Step 2. 가상환경(Virtual Environment) 확인

가장 빈번한 원인은 '가상환경 불일치'입니다. VS Code나 PyCharm 같은 에디터에서 선택한 파이썬 인터프리터가 패키지를 설치한 환경과 다를 수 있습니다.

• 확인 방법: 에디터 하단에 표시된 파이썬 버전을 클릭하여, 내가 패키지를 설치한 가상환경이 선택되어 있는지 확인하세요.
• 터미널 확인: 터미널 앞에 (venv)와 같이 환경 이름이 떠 있는지 체크해야 합니다.

Step 3. sys.path 경로 확인 및 추가

직접 만든 .py 파일을 임포트할 때 발생한다면, 파이썬이 파일을 검색하는 경로 리스트인 sys.path를 확인해야 합니다.

import sys
print(sys.path) # 파이썬이 모듈을 찾는 경로 목록 출력

만약 파일이 있는 폴더가 목록에 없다면 아래 코드로 임시 추가가 가능합니다.

import sys
sys.path.append('/모듈이_있는_폴더_경로')

---

3. VS Code/PyCharm 사용자들을 위한 꿀팁

VS Code의 경우

설치를 했는데도 에디터에서 빨간 줄이 사라지지 않는다면 Ctrl + Shift + P를 누르고 "Python: Select Interpreter"를 검색하여 올바른 환경을 다시 지정해 보세요.

패키지 설치 시 주의사항

여러 개의 파이썬 버전이 설치된 경우 pip 명령어가 엉뚱한 곳에 설치할 수 있습니다. 이럴 때는 아래와 같이 명시적으로 설치하는 것이 가장 안전합니다.

# 현재 실행 중인 파이썬에 직접 설치
python -m pip install 패키지명

---

핵심 요약 정리

1. 설치 확인: 터미널에서 pip list로 모듈이 있는지 확인한다.
2. 환경 일치: 패키지를 설치한 환경과 실행 중인 인터프리터(가상환경)가 같은지 확인한다.
3. 이름 확인: 대소문자나 언더바(_)와 하이픈(-) 등의 오타를 체크한다.
4. 절대 경로: 커스텀 모듈의 경우 sys.path를 통해 경로가 등록되어 있는지 확인한다.