Python에서 "No Module Named Matplotlib" 에러 해결하기

2. 사용 중인 Python 확인

   ```python
   import sys; print(sys.executable)
   ```

3. Jupyter Notebook 사용 시 (가장 흔한 원인):

   ```python
   %pip install matplotlib
   ```

   이후 커널 재시작.

4. 작업 디렉터리에 `matplotlib.py`라는 파일이 없는지 확인.

그래도 안 된다면 계속 읽어보세요 — 원인이 아래에 있습니다.

---

# 이 에러가 발생하는 이유

`ModuleNotFoundError` 가 발생하는 상황:

* 사용 중인 환경에 Matplotlib이 설치되어 있지 않은 경우
* 예상과 다른 Python 인터프리터로 코드를 실행하는 경우
* Jupyter가 Matplotlib이 설치되지 않은 커널을 사용하는 경우
* IDE에서 잘못된 인터프리터를 사용하는 경우
* 프로젝트 내의 파일이 실제 `matplotlib` 라이브러리를 가리는 경우(이름 충돌)
* 환경 변수, 경로, 가상환경 설정이 잘못된 경우
* 설치가 손상되었거나 불완전한 경우

---

## 🧠 원인 & 해결 한눈에 보기

| **원인**                           | **해결 요약**                                                                   |
| ---------------------------------- | ------------------------------------------------------------------------------- |
| Matplotlib 미설치                  | `python -m pip install matplotlib` (또는 `conda install matplotlib`) 실행       |
| 여러 Python 버전 사용              | `python -m pip install ...`로 pip와 인터프리터를 일치시켜 설치                  |
| 잘못된 hashbang                   | `#!` 라인 수정 또는 `python3 script.py` 로 명시적 실행                          |
| 잘못된 PATH / PYTHONPATH          | `sys.path`에 site-packages 포함 여부 확인·환경 변수 초기화                      |
| 설치 손상                          | `pip uninstall matplotlib` 후 재설치                                            |
| 가상환경 미활성화                  | venv 활성화 후 설치/실행                                                        |
| IDE 인터프리터 불일치              | VS Code / PyCharm에서 올바른 인터프리터 선택                                   |
| Jupyter 커널 불일치                | 올바른 커널 사용 또는 Notebook 안에서 Matplotlib 설치                          |
| 오타 또는 대소문자 문제            | 모두 소문자 `import matplotlib` 사용                                            |
| 이름 충돌(파일/폴더가 라이브러리 가림) | 프로젝트 내 `matplotlib.py` 같은 파일/폴더 이름 변경                           |

---

# 이슈 1: Matplotlib이 설치되어 있지 않은 경우

### ✔ 발생 이유

현재 사용 중인 Python 환경에 라이브러리가 아예 설치되어 있지 않습니다.

### ✔ 해결 방법

pip 또는 conda로 설치합니다:

```bash
python -m pip install matplotlib
# or
pip install matplotlib
```

Conda 사용자:

```bash
conda install matplotlib
```

설치 확인:

```python
import matplotlib
print(matplotlib.__version__)
```

이때 import가 정상 동작하면 해결된 것입니다.

---

# 이슈 2: 여러 Python 버전 또는 환경을 사용하는 경우

실제 현업에서 **가장 자주 발생하는 원인**입니다.

예시:

* Python 3.11에 Matplotlib을 설치했지만  
  스크립트는 Python 3.9로 실행하는 경우
* Matplotlib을 가상환경에 설치했지만  
  스크립트는 시스템 전역 Python으로 실행하는 경우

### ✔ 해결: pip가 사용하는 Python과 실행 Python을 맞추기

사용 중인 Python 인터프리터 확인:

```bash
python -V
python3 -V
```

pip가 어느 Python을 가리키는지 확인:

```bash
pip --version
```

권장 설치 방법(가장 안전):

```bash
python -m pip install matplotlib
```

Windows 사용자는:

```bash
py -3.11 -m pip install matplotlib
```

이렇게 하면 pip가 항상 지정한 인터프리터에 설치하도록 강제할 수 있습니다.

---

# 이슈 3: 잘못된 스크립트 Hashbang (Linux/Mac)

스크립트 첫 줄이 아래와 같은 경우:

```bash
#!/usr/bin/python
```

Python 2 또는 시스템 기본 Python으로 실행될 수 있습니다.

### ✔ 해결

올바른 shebang 사용:

```bash
#!/usr/bin/env python3
```

또는 다음처럼 명시적으로 실행:

```bash
python3 plot.py
```

---

# 이슈 4: Python이 잘못된 경로를 검색하는 경우 (sys.path / 환경 변수)

대표적인 원인:

* `PYTHONPATH` 잘못 설정
* 깨진 환경 변수 설정
* 비표준 위치에 site-packages를 따로 둔 경우

### ✔ 해결

Python이 어디를 검색하는지 확인:

```python
import sys
print(sys.path)
```

Matplotlib 설치 위치 확인:

```bash
pip show matplotlib
```

이 경로가 Python의 검색 경로에 없다면, 다음과 같이 해결할 수 있습니다.

* 잘못된 `PYTHONPATH` 제거
* Matplotlib을 표준 방식으로 다시 설치
* 꼭 필요한 경우가 아니라면 수동으로 path를 건드리지 않기

임시 진단용(장기 사용 비권장):

```python
import sys
sys.path.append("/path/to/matplotlib")
```

---

# 이슈 5: 설치가 손상되었거나 일부만 설치된 경우

설치 도중 중단되었거나 의존성 설치에 실패한 경우, Matplotlib이 반쯤만 설치된 상태일 수 있습니다.

### ✔ 해결: 깔끔하게 재설치

```bash
pip uninstall matplotlib
pip install matplotlib --no-cache-dir
```

의존성 상태 확인:

```bash
pip check
```

---

# 이슈 6: 가상환경(venv)이 활성화되지 않은 경우

Matplotlib을 가상환경에 설치했지만,  
Python은 가상환경 밖에서 실행하고 있을 수 있습니다.

### ✔ 해결: 먼저 가상환경 활성화

**Windows**

```bash
.\venv\Scripts\activate
```

**macOS/Linux**

```bash
source venv/bin/activate
```

그 다음 설치:

```bash
pip install matplotlib
```

Python이 가상환경을 가리키는지 확인:

```python
import sys; print(sys.executable)
```

---

# 이슈 7: IDE가 잘못된 인터프리터를 사용하는 경우 (VS Code / PyCharm)

### ✔ VS Code에서 해결

오른쪽 하단 인터프리터 표시 클릭 → 올바른 env 선택  
또는 명령 팔레트에서:

```
Ctrl + Shift + P → “Python: Select Interpreter”
```

### ✔ PyCharm에서 해결

Preferences → Project → Python Interpreter → 올바른 env 선택

IDE가 잘못된 Python을 사용하면, 실제로는 설치되어 있어도 Matplotlib이 “없는 것처럼” 보일 수 있습니다.

---

# 이슈 8: Jupyter Notebook 커널 불일치

*(데이터 사이언스 워크플로에서 가장 흔한 원인)*

예시 상황:

* 터미널에서 Matplotlib을 설치했는데
* Jupyter Notebook은 전혀 다른 Python으로 실행 중인 경우

### ✔ 해결 1: Notebook이 사용하는 Python 확인

```python
import sys; print(sys.executable)
```

### ✔ 해결 2: 해당 커널 안에서 Matplotlib 설치

```python
%pip install matplotlib
```

커널 재시작 후 다시 import.

### ✔ 해결 3: 사용 중인 env를 Jupyter 커널로 등록

```bash
python -m ipykernel install --user --name myenv --display-name "Python (myenv)"
```

---

# 이슈 9: import 문 오타 또는 대소문자 문제

올바른 예:

```python
import matplotlib
import matplotlib.pyplot as plt
```

잘못된 예:

❌ `import Matplotlib`  
❌ `import matplotllib`

---

# 이슈 10: 이름 충돌 (Shadowing)

프로젝트 안에 다음과 같은 파일/폴더가 있다면:

* `matplotlib.py`
* `matplotlib/` 라는 폴더

Python은 실제 라이브러리 대신 **해당 파일/폴더를 import** 하게 됩니다.

### ✔ 해결

파일/폴더 이름 변경:

```
my_plot_test.py
```

자동 생성된 캐시 삭제:

```
__pycache__/
```

---

# 요약 테이블 (업데이트 & 간결 정리)

| **원인**          | **해결 방법**                               |
| ----------------- | ------------------------------------------- |
| 미설치            | pip/conda로 설치                            |
| 잘못된 인터프리터 | `python -m pip install` 사용                |
| 잘못된 hashbang   | `#!/usr/bin/env python3` 사용               |
| 잘못된 경로       | `sys.path` 확인·환경 변수 초기화            |
| 설치 손상         | `--no-cache-dir` 옵션으로 재설치            |
| venv 미활성화     | 실행 전 가상환경 활성화                     |
| IDE 불일치        | 올바른 인터프리터 선택                      |
| Jupyter 불일치    | `%pip`로 설치 후 올바른 커널 사용           |
| 오타              | 소문자 `matplotlib`로 수정                  |
| 이름 충돌         | 로컬 파일/폴더 이름 변경                    |

---

# 🔥 대안: 환경 설정 없이 빠르게 시각화하는 방법 — PyGWalker

Python 환경 문제를 계속 디버깅하는 게 지겹고, 더 빠른 데이터 시각화 방법이 필요하다면, **PyGWalker**를 사용해보세요.  
Jupyter에서 바로 동작하는 오픈소스 드래그앤드롭 시각 분석 도구입니다.

```bash
pip install pygwalker
```

```python
import pygwalker as pyg
gwalker = pyg.walk(df)
```

온라인에서 바로 체험해 보기:

| Kaggle                                                                                       | Google Colab                                                                | GitHub                                                                         |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| [https://www.kaggle.com/asmdef/pygwalker-test](https://www.kaggle.com/asmdef/pygwalker-test) | [https://colab.research.google.com/](https://colab.research.google.com/)... | [https://github.com/Kanaries/pygwalker](https://github.com/Kanaries/pygwalker) |

---

# FAQ

### 1. Matplotlib을 설치했는데도 계속 에러가 납니다. 왜 그런가요?

Matplotlib이 설치된 Python 인터프리터와, 실제로 코드를 실행하는 인터프리터가 서로 다를 가능성이 큽니다.

### 2. 재설치 후에도 에러가 계속됩니다. 이유가 뭔가요?

설치가 손상되었거나, Python이 잘못된 경로를 검색하고 있을 수 있습니다. 다음과 같이 캐시를 비우고 재설치해 보세요.

```bash
pip install matplotlib --no-cache-dir
```

### 3. Matplotlib을 사용자 지정 디렉터리에 설치할 수 있나요?

가능합니다. 다만 그 디렉터리가 Python의 `sys.path`에 포함되어 있어야 합니다.  
일반적인 설치 방법을 사용하는 것이 훨씬 단순하고 안정적입니다.

---

<JSONldScript
faq={{
data: [
{
question: "Why do I encounter the 'No Module Named Matplotlib' error even after installation?",
answer: "You are likely running Python from a different interpreter than the one where Matplotlib is installed.",
},
{
question: "Why does the error persist even after correcting the Python version?",
answer: "You may have a corrupted installation or Python is checking the wrong path. Try reinstalling or fixing paths.",
},
{
question: "Can I install Matplotlib in a custom directory?",
answer: "Yes, but Python must include that directory in its search paths (`sys.path`).",
}
]
}}
/>