본문 바로가기
카테고리 없음

Python "ModuleNotFoundError: No module named" 해결법

by smartmove 2025. 4. 4.

Python "ModuleNotFoundError: No module named" 해결법

Python에서 "ModuleNotFoundError: No module named" 오류는 특정 모듈이 존재하지 않거나, 제대로 설치되지 않은 경우에 발생합니다. 이 오류는 Python 코드에서 import문을 사용할 때 발생하며, Python이 지정한 모듈을 찾을 수 없을 때 나타납니다. 이 글에서는 이 오류의 원인과 해결 방법을 살펴보겠습니다.

1. 'ModuleNotFoundError: No module named' 오류 원인

"ModuleNotFoundError: No module named" 오류는 주로 다음과 같은 경우에 발생합니다:

  • 모듈이 설치되지 않았거나 올바르게 설치되지 않았을 때
  • 모듈 이름을 잘못 입력했을 때
  • 가상 환경(virtual environment)을 사용 중인데, 해당 환경에 모듈이 설치되지 않았을 때
  • PYTHONPATH 설정이 잘못되어 모듈을 찾을 수 없을 때

이 오류는 기본적으로 모듈을 찾을 수 없을 때 발생하므로, 위와 같은 이유들이 원인으로 작용할 수 있습니다. 이제 각 원인에 대한 해결 방법을 살펴보겠습니다.

2. 'ModuleNotFoundError: No module named' 오류 해결 방법

이 오류를 해결하기 위해서는 몇 가지 방법을 시도할 수 있습니다. 아래에서 주요 해결 방법들을 설명합니다.

2.1 모듈 설치 확인 및 설치하기

가장 일반적인 원인 중 하나는 모듈이 설치되지 않았거나 제대로 설치되지 않은 경우입니다. 이 경우, 먼저 모듈이 설치되어 있는지 확인하고, 설치되지 않았다면 `pip`를 사용하여 모듈을 설치해야 합니다.


# 모듈이 설치되어 있는지 확인
pip show 

# 모듈이 설치되지 않았다면, pip를 사용하여 설치
pip install

위 코드에서 ``을 오류가 발생한 모듈 이름으로 바꾸고 실행합니다. 예를 들어, `numpy` 모듈이 없다는 오류가 발생하면, 다음과 같이 설치할 수 있습니다.


pip install numpy

이렇게 하면 해당 모듈이 설치되고, 오류가 해결될 수 있습니다.

2.2 모듈 이름 확인하기

모듈 이름을 잘못 입력했을 경우에도 "ModuleNotFoundError: No module named" 오류가 발생할 수 있습니다. 특히 대소문자가 정확히 일치하지 않으면 오류가 발생할 수 있습니다. 모듈 이름이 정확한지 확인하고, 필요한 경우 대소문자를 바르게 입력해야 합니다.


# 잘못된 모듈 이름 사용 예
import numpy   # 'numpy'가 아니라 'Numpy'로 대소문자가 다를 수 있음

# 올바른 모듈 이름 사용 예
import numpy   # 'numpy'는 소문자로 사용해야 함

모듈 이름을 정확하게 입력했는지 확인하는 것이 중요합니다. Python은 대소문자를 구분하므로, 정확한 이름을 확인한 후 사용해야 합니다.

2.3 가상 환경 확인하기

Python에서 가상 환경을 사용하는 경우, 해당 가상 환경에 모듈이 설치되지 않으면 "ModuleNotFoundError: No module named" 오류가 발생할 수 있습니다. 이 경우, 가상 환경이 활성화되어 있는지 확인하고, 해당 환경에 모듈을 설치해야 합니다.


# 가상 환경 활성화
# Windows
.\venv\Scripts\activate

# Mac/Linux
source venv/bin/activate

가상 환경을 활성화한 후, 해당 환경에 모듈을 설치해야 합니다. 예를 들어, `numpy`를 설치하려면 다음 명령어를 실행합니다.


pip install numpy

이 방법으로 가상 환경에서 필요한 모듈을 설치한 후, 다시 실행하면 오류가 해결됩니다.

2.4 PYTHONPATH 확인하기

PYTHONPATH 환경 변수가 잘못 설정되어 있는 경우, Python이 모듈을 찾지 못할 수 있습니다. 이 경우, Python이 모듈을 찾을 수 있는 경로를 확인하고, 필요한 경우 경로를 수정해야 합니다. 다음 명령어를 사용하여 현재 설정된 PYTHONPATH를 확인할 수 있습니다.


import sys
print(sys.path)

위 명령어를 실행하면 Python이 모듈을 찾는 경로 리스트를 확인할 수 있습니다. 만약 모듈이 해당 경로에 없다면, 경로를 수정하거나 모듈을 올바른 경로에 설치해야 합니다.

2.5 패키지와 모듈 구분하기

Python에서는 모듈과 패키지가 구분됩니다. 패키지 내부에 있는 모듈을 import하려면 패키지 구조를 정확히 이해하고 import 구문을 작성해야 합니다. 예를 들어, `pandas` 라이브러리에서 `DataFrame`을 사용하려면 `pandas.DataFrame`으로 접근해야 합니다.


# 잘못된 import 예
import pandas.DataFrame  # 오류 발생

# 올바른 import 예
import pandas
df = pandas.DataFrame()  # 정상적으로 DataFrame 사용

이와 같이 패키지와 모듈의 구조를 정확히 이해하고, 올바르게 import 문을 작성해야 오류를 방지할 수 있습니다.

3. 결론

"ModuleNotFoundError: No module named" 오류는 모듈이 설치되지 않았거나, 잘못된 경로로 참조할 때 발생합니다. 이 오류를 해결하려면 다음과 같은 방법을 사용할 수 있습니다:

  • 모듈이 설치되지 않았을 경우, `pip install `으로 설치
  • 모듈 이름을 정확하게 입력
  • 가상 환경을 확인하고, 해당 환경에 모듈을 설치
  • PYTHONPATH 설정을 확인하여 경로 수정
  • 패키지와 모듈을 구분하여 올바르게 import

위 방법들을 통해 "ModuleNotFoundError" 오류를 쉽게 해결할 수 있으며, Python 프로젝트에서 발생하는 다양한 모듈 관련 문제를 처리할 수 있습니다.

티스토리툴바