Skip to content

파이썬에서 "No Module Named Matplotlib" 오류를 해결하는 방법

**ModuleNotFoundError: No module named 'matplotlib'**는 데이터 시각화 작업 중 파이썬 개발자들이 자주 마주치는 오류입니다. 이 메시지는 파이썬이 환경 내에서 Matplotlib 라이브러리를 찾지 못했다는 의미입니다 (자세한 내용은 Facing 'No Module Named Matplotlib' Error? Here is the Solution – Kanaries (opens in a new tab)가 참고 자료입니다). 좋은 소식은, 이 오류는 대부분 쉽게 해결 가능하다는 점입니다. 이번 가이드에서는 오류의 모든 원인과 해결 방법을 단계별로 설명드리겠습니다.

초보자 또는 환경 설정이 처음이신 분도 걱정 마세요! 친근하고 도움을 주는 톤으로 작성된 이 안내는 Matplotlib을 빠르게 설치하고 사용할 수 있도록 도와드릴 것입니다. 바로 시작해 볼까요?

오류 이해하기

ModuleNotFoundError: No module named 'matplotlib' 메시지가 뜬다는 건 파이썬이 현재 사용하는 인터프리터의 모듈 검색 경로에 **matplotlib**이 없다는 의미입니다. 이는 여러 가지 원인으로 발생할 수 있습니다:

  • Matplotlib가 설치되지 않음: 해당 환경에 라이브러리가 아예 없음.
  • 여러 버전 또는 가상 환경 사용: 한 Python 환경에는 설치되어 있는데, 코드 실행은 다른 환경에서 하는 경우.
  • 잘못된 스크립트 호출 방법(해시뱅이 문제): #! 등으로 Python 버전이 다르게 호출되어 라이브러리를 찾지 못하는 경우.
  • Python 환경 변수 또는 PATH 문제: Python이 패키지를 찾는 경로가 올바르지 않거나, 환경변수가 설정 안 됨.
  • 손상된 설치: Matplotlib 설치 파일이 깨지거나 제대로 끝나지 않은 경우.
  • 가상 환경 미활성화: 가상환경(virtualenv 또는 Conda)을 활성화하지 않아서 환경 내 라이브러리 접근 실패.
  • IDE 또는 Jupyter의 인터프리터 설정 문제: 활용하는 IDE 또는 노트북 커널이 올바른 환경을 사용하지 않는 경우.
  • 임포트 문구 오타 또는 대소문자 오류: import matplotlib의 철자가 틀리거나 대소문자 오류.
  • 이름 충돌: 프로젝트 내에 matplotlib라는 이름의 파일 또는 폴더가 있어서 라이브러리와 충돌하는 경우.

원인별 빠른 체크 표

원인해결 방법 요약
Matplotlib 미설치pip install matplotlib 또는 conda로 설치.
여러 Python 환경 또는 버전사용하는 인터프리터에 맞게 설치; python -m pip install ... 사용.
잘못된 스크립트 호출 또는 해시뱅이 문제적절한 Python 버전과 함께 직접 명령 또는 해시뱅 수정.
PATH 또는 환경 변수 문제sys.path 확인 후 필요 시 PYTHONPATH 설정 또는 재설치.
손상된 설치삭제 후 재설치.
가상 환경 미활성화가상환경 활성화 후 설치 및 실행.
IDE 또는 코드 편집기 설정 문제인터프리터 또는 가상환경 제대로 지정.
Jupyter 커널 문제커널 재선택 또는 새로운 커널 등록.
임포트 오타 또는 대소문자 오류import matplotlib 소문자 사용!
충돌하는 이름 또는 폴더 이름matplotlib.py 등 이름 변경.

이후 섹션에서는 각각의 원인별 해결책을 차근차근 설명드리니, 차례대로 점검하시면서 수정하시면 됩니다.

1. Matplotlib가 설치되지 않은 경우

가장 흔한 원인! Matplotlib 라이브러리를 설치하지 않아서 발생하는 경우입니다. 설치가 되지 않으면 Python은 당장 라이브러리를 찾을 방법이 없습니다.

해결책: Matplotlib 설치하기

파이썬의 패키지 매니저인 pip 또는 conda를 이용하세요.

  • pip 사용 시:
pip install matplotlib
  • Python 버전별로 명시적 실행:
python3 -m pip install matplotlib

이 명령은 PyPI에서 최신 Matplotlib을 다운로드하여 설치합니다. 여러 파이썬 버전이 깔려 있다면, 자신이 사용하는 버전에 맞게 명령어를 작성하세요.

  • conda 사용 시:
conda install matplotlib

이 명령은 Anaconda 또는 Miniconda 환경에 설치합니다. 환경별로 활성화한 후 실행하세요 (conda activate YourEnvName).

설치 후, 간단히 확인해 보면:

import matplotlib
print(matplotlib.__version__)

이 명령이 에러 없이 버전을 출력한다면 성공한 것입니다. 만약 여전히 오류가 난다면, 다음 섹션으로 넘어가서 해결하세요.

2. 여러 Python 버전 또는 환경 문제가 원인인 경우

시스템에 여러 Python 버전 또는 가상 환경이 설치되어 있으면, 라이브러리 설치와 사용 환경이 일치하지 않아 문제가 발생할 수 있습니다.

해결책: 적절한 환경에서 지도하기

  1. 사용하는 파이썬 버전 확인:
python --version

또는 Python 쉘에서:

import sys
print(sys.executable)
print(sys.version)

이 정보를 통해 어떤 환경인지 파악하세요.

  1. pip가 가리키는 Python 버전 점검:
pip --version

이때 출력되는 Python 버전과 실행한 python 명령의 버전이 다르면 예상과 달리 다른 환경을 사용 중인 겁니다.

  1. 올바른 Python에 라이브러리 설치하기:
python3.x -m pip install matplotlib

예를 들어, Python 3.10을 사용한다면:

python3.10 -m pip install matplotlib

이 명령어로 원하는 환경에 설치하세요.

  1. 가상환경 또는 conda 환경 활용: 환경을 활성화 한 후 설치합니다.
# virtualenv 또는 venv
source env/bin/activate  # 유닉스/macOS
.\env\Scripts\activate  # 윈도우
pip install matplotlib

이렇게 환경별로 올바르게 설치하면 문제 해결됩니다.

3. 스크립트 해시뱅이 꼬인 경우

쉘에서 Python 스크립트를 직접 실행할 때, 파일 맨 위에 #! 줄이 있습니다. 이 해시뱅이 올바른 Python 버전을 가리키지 않거나, 잘못된 경로를 참조하는 경우입니다.

해결책: 해시뱅 수정 또는 명령어 명확히

  • 스크립트 맨 앞에 있는 #!를
#!/usr/bin/env python3

로 수정하세요. 이것은 시스템 환경에서 Python 3를 찾아서 사용하게 합니다.

  • 또는 그냥 커맨드라인에서 명시적으로 실행:
python3 your_script.py

이렇게 하면 호출하는 Python 버전과 라이브러리 환경이 일치하게 됩니다.

4. PATH 또는 PYTHONPATH 환경 변수 문제

Python이 라이브러리 검색하는 경로에 문제가 있으면 라이브러리를 못 찾게 됩니다.

해결책: 경로 확인과 수정

  1. 현재 Python의 검색 경로 확인:
import sys
print(sys.path)
  1. Matplotlib이 설치된 위치가 포함되어 있지 않다면:
  • PYTHONPATH 환경 변수에 경로를 추가하세요:
export PYTHONPATH="$PYTHONPATH:/경로/to/matplotlib"
  • 또는 파이썬 코드 내에서 일시적으로 추가:
import sys
sys.path.append('/경로/to/matplotlib')
import matplotlib
  1. 권장하는 방법: 패키지를 표준 위치에 설치하고, 환경변수보다 임포트 경로를 명확히 하는 것이 바람직합니다.

5. 설치된 라이브러리 손상 또는 불완전한 경우

설치 도중 문제가 생겨서 제대로 설치되지 않았을 수 있습니다.

해결책: 재설치 수행

  1. 기존 설치 삭제:
pip uninstall matplotlib
  1. 클린히 재설치:
pip install --no-cache-dir matplotlib

이후 다시 시도하세요.

6. 가상 환경 활성화 여부

가상 환경을 사용하는 경우, 활성화하지 않으면 전역 Python 환경의 라이브러리만 참조하게 됩니다.

해결책: 가상환경 활성화

  • 활성화 후 설치:
source env/bin/activate  # 유닉스/맥
.\env\Scripts\activate  # 윈도우
pip install matplotlib
  • 코드 실행도 활성화된 환경에서 진행하세요.

7. IDE 또는 편집기에서 인터프리터 선택이 잘못된 경우

IDE에서는 프로젝트 또는 환경별로 인터프리터를 선택할 수 있습니다. 여기서 선택이 잘못되면 설치된 라이브러리를 못 찾을 수 있습니다.

해결책

  • PyCharm: Settings > Project > Interpreter에서 올바른 인터프리터 선택
  • VS Code: 하단 상태바 또는 Ctrl+Shift+P > Python: Select Interpreter로 환경 선택
  • 그 외 IDE: 환경 또는 인터프리터 메뉴를 이용하여 올바른 환경을 지정

설정 이후 다시 실행하면, 라이브러리가 제대로 인식될 가능성이 높습니다.

8. Jupyter Notebook의 커널가 일치하지 않는 경우

Jupyter Notebook에서 라이브러리 설치 후 바로 사용할 때, 커널이 올바른 환경을 사용하지 않으면 ModuleNotFoundError가 발생합니다.

해결책

  1. 현재 커널의 Python 경로 확인:
import sys
print(sys.executable)
  1. 원하는 환경의 커널 선택 또는 등록:
  • 새 커널 등록:
python -m ipykernel install --user --name=특정환경 --display-name "Python (특정환경)"
  • 노트북 상단 커널 선택 메뉴에서 해당 환경 선택
  1. 실행 환경 내에 Matplotlib 설치:
%pip install matplotlib
  • 또한, 설치 후 커널 재시작(Reset Kernel) 후 다시 시도하세요.

이 과정을 거치면 Jupyter에서도 올바른 환경에서 라이브러리를 사용할 수 있습니다.

9. 임포트 문법 오타 또는 대소문자 오류

파이썬은 대소문자를 구별합니다. import Matplotlib이 아닌 import matplotlib라고 써야 합니다.

해결책

  • 항상 소문자: import matplotlib
  • 잘못된 대문자 수정: 오타를 바로 잡고 다시 시도하세요.

10. 이름 충돌(네이밍 문제)

프로젝트 내에 matplotlib.py같은 파일이 있거나 같은 이름 폴더가 있으면, 파이썬이 내장 라이브러리 대신 자신의 파일을 참조할 수 있습니다.

해결책

  • 파일 이름 또는 폴더 이름을 matplotlib가 아닌 다른 것으로 변경하세요.
  • 캐시된 파이썬 바이트코드를 삭제:
rm -rf __pycache__  # 유닉스/맥
del __pycache__  # 윈도우

이후 다시 임포트하면 제대로 된 라이브러리를 참조할 수 있습니다.

결론 및 추천 방법 정리

  • pip install matplotlib 또는 conda install matplotlib로 먼저 설치
  • 사용하는 파이썬 인터프리터와 설치 환경 일치시키기
  • 가상 환경 활성화 후 설치 및 실행
  • IDE 또는 노트북의 커널, 인터프리터 재선택
  • 이름 충돌 방지 — 파일명 체크
  • 필요 시 재설치 또는 환경 재설정

이 가이드대로 차근차근 검증하면, 대부분의 No Module Named Matplotlib 오류는 쉽게 해결됩니다. 문제 해결 후에는 항상 import matplotlib가 문제없이 작동하는지 확인하세요.

대체 시각화 라이브러리: PyGWalker 소개

Matplotlib 대신 데이터 시각화를 좀 더 간단하고 빠르게 하고 싶다면 PyGWalker (opens in a new tab)가 좋은 선택입니다.

PyGWalker 활용 모습 (opens in a new tab)

복잡한 파이썬 코드 없이 데이터 업로드 후 드래그 앤 드롭으로 다양한 차트를 만들 수 있습니다. 아래 영상도 참고하세요:


파이썬 Jupyter 노트북에서 PyGWalker 사용법:

pip install pygwalker
import pygwalker as pyg
gwalker = pyg.walk(df)

Kaggle 또는 Google Colab에서도 사용할 수 있습니다:

Kaggle에서 PyGWalker 실행하기 (opens in a new tab)Colab에서 PyGWalker 실행하기 (opens in a new tab)GitHub에 별⭐️ 주기 (opens in a new tab)
Kaggle에서 PyGWalker 바로 실행 (opens in a new tab)Colab에서 바로 실행 (opens in a new tab)GitHub 별줌 (opens in a new tab)

PyGWalker는 오픈소스 커뮤니티의 지원으로 만들어졌습니다. GitHub를 방문하고 별⭐️ 주세요!

자주 묻는 질문

  1. 설치 후에도 'No Module Named Matplotlib' 에러가 계속 나와요. 왜 그런 걸까요?

아마도 파이썬을 실행하는 버전과 Matplotlib이 설치된 버전이 다를 가능성이 높습니다. 파이썬 버전과 환경을 다시 확인하세요.

  1. 파이썬 버전 맞춰서 설치했는데도 오류가 계속돼요. 왜 그런 걸까요?

손상되었거나 불완전하게 설치됐거나, 파이썬이 잘못된 위치에서 패키지를 찾고 있을 수 있습니다. 재설치하거나 경로를 환경변수에 등록하세요.

  1. 지정한 디렉터리에 라이브러리 설치하면 문제 없나요?

파이썬은 sys.path에 등록된 디렉터리에서만 모듈을 찾기 때문에, 해당 위치가 포함되어 있으면 문제없이 찾습니다. 하지만 추천하는 방법은 패키지를 표준 위치에 설치하는 것입니다.

이 가이드에 따라 차근차근 점검하면, No Module Named Matplotlib 오류는 쉽게 해소됩니다. 성공적으로 라이브러리 임포트하고 멋진 데이터 시각화 하시길 바랍니다!