Python ModuleNotFoundError 해결 방법 — 원인부터 완벽 해결까지

저도 처음에 pip install을 분명히 했는데 ModuleNotFoundError가 계속 나와서 한참을 헤맸습니다. 알고 보니 가상환경이 활성화가 안 된 상태에서 설치했던 게 문제였습니다.

가상환경을 사용 중이라면 패키지를 설치하거나 코드를 실행하기 전에 반드시 가상환경이 활성화되었는지 확인해야 합니다. 아래의 절차를 통해 현재 환경을 점검해 보세요. 

Python을 배우다 보면 누구나 한 번은 마주치는 오류가 있습니다. 바로 ModuleNotFoundError: No module named 'XXX' 입니다. vscode에서 코드를 실행하는 순간 이 빨간 글씨가 등장하면 당황스럽지만, 사실 이 오류는 원인이 명확하고 해결 방법도 분명합니다. 이 글에서는 ModuleNotFoundError가 발생하는 다섯 가지 원인과 상황별 해결법을 단계별로 정리해 드리겠습니다.

ModuleNotFoundError란 무엇인가 — 택배 주소를 찾을 수 없는 상황

오류의 정체

ModuleNotFoundError는 Python이 import 문으로 모듈을 불러오려 했지만 해당 모듈을 찾지 못했을 때 발생합니다. 아래처럼 생긴 오류 메시지가 바로 그것입니다.

ModuleNotFoundError: No module named 'pandas'

택배에 비유하면 이렇습니다. import pandas는 "판다스라는 이름의 택배를 가져와줘"라는 요청입니다. 그런데 창고(Python 환경)에 그 택배가 없으면 "해당 주소로 배달된 물건이 없습니다"라는 메시지가 뜨는 것입니다. 해결책은 단순합니다. 창고에 물건을 채워 넣거나(설치), 올바른 창고를 열거나(환경 확인), 주소를 정확히 쓰거나(경로 설정) 하면 됩니다.

오류가 발생하는 다섯 가지 상황

  • 원인 1 — 라이브러리를 아예 설치하지 않은 경우
  • 원인 2 — 가상환경이 활성화되지 않은 상태에서 설치한 경우
  • 원인 3 — VS Code의 Python 인터프리터가 잘못 설정된 경우
  • 원인 4 — 모듈 이름을 오타로 잘못 입력한 경우
  • 원인 5 — 직접 만든 모듈의 경로가 Python에 등록되지 않은 경우

원인 1 — 라이브러리가 설치되지 않은 경우

확인 방법

가장 먼저 해당 라이브러리가 실제로 설치되어 있는지 확인합니다.

pip list

목록에 해당 라이브러리가 없다면 설치가 안 된 것입니다.

해결 방법 — pip install

pip install pandas

여러 라이브러리를 한 번에 설치하려면 아래처럼 입력합니다.

pip install pandas numpy matplotlib requests

설치 후 다시 코드를 실행해서 오류가 사라지는지 확인합니다.


💡 패키지 이름과 import 이름이 다른 경우: 설치할 때 이름과 import할 때 이름이 다른 라이브러리가 있습니다. 아래가 대표적인 예입니다.

pip install 이름 import 이름
pillow from PIL import Image
python-dotenv from dotenv import load_dotenv
scikit-learn import sklearn
beautifulsoup4 from bs4 import BeautifulSoup
opencv-python import cv2

원인 2 — 가상환경 문제 (가장 흔한 원인)

왜 이런 일이 생기는가

이것이 ModuleNotFoundError의 가장 흔한 원인입니다. 가상환경 밖에서 pip install을 했거나, 가상환경 A에 설치했는데 가상환경 B가 활성화된 상태에서 코드를 실행하는 경우입니다.

마치 회사 창고에 물건을 넣어뒀는데, 집 창고를 열어서 "왜 없어?"라고 하는 상황과 같습니다. 물건은 분명히 있지만 엉뚱한 창고를 열고 있는 것입니다.

확인 방법

터미널에서 현재 활성화된 Python이 어디 있는지 확인합니다.

# Windows
where python

# macOS / Linux
which python3


경로가 venv/Scripts/python.exe (Windows) 또는 venv/bin/python (macOS) 형태여야 가상환경이 활성화된 것입니다.

해결 방법 — 가상환경 활성화 후 재설치

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

# macOS / Linux
source venv/bin/activate

# 활성화 확인 — 프롬프트 앞에 (venv) 표시 확인 후 설치
pip install pandas

원인 3 — VS Code 인터프리터 설정 문제

vscode에서만 오류가 나는 경우

터미널에서 직접 실행하면 잘 되는데 vscode의 실행 버튼(▶)을 누르면 ModuleNotFoundError가 발생하는 경우가 있습니다. 이는 vscode가 가상환경의 Python이 아닌 시스템 Python을 사용하도록 설정되어 있기 때문입니다.

해결 방법 — 인터프리터 변경

  1. Ctrl + Shift + P (macOS는 Cmd + Shift + P)를 누릅니다.
  2. Python: Select Interpreter를 입력하고 선택합니다.
  3. 목록에서 ./venv/Scripts/python.exe 또는 ./venv/bin/python 항목을 선택합니다.




선택 후 vscode 하단 상태표시줄에 선택한 Python 경로가 표시되면 완료입니다. 이후 실행 버튼을 눌러도 가상환경의 Python이 사용됩니다.

pip과 python이 서로 다른 환경을 가리키는 경우

# python과 pip이 같은 환경인지 확인
python -m pip install pandas

pip install 대신 python -m pip install을 사용하면 현재 실행 중인 Python과 동일한 환경에 라이브러리가 설치됩니다. 환경 불일치 문제를 가장 확실하게 방지하는 방법입니다.

원인 4 — 오타 및 모듈 이름 혼동

대소문자 구분과 철자 오류

Python의 import는 대소문자와 철자를 정확하게 구분합니다. 아래는 흔히 발생하는 오타 예시입니다.

# 잘못된 방법
import Pandas        # 대문자 P
import panda         # s 누락
import numppy        # p 중복

# 올바른 방법
import pandas
import numpy

현재 파일 이름이 라이브러리 이름과 같은 경우

이 경우는 원인을 찾기 특히 어렵습니다. 예를 들어 본인이 만든 파일 이름이 requests.py라면, import requests를 실행할 때 외부 라이브러리 대신 본인의 파일을 불러오려다 충돌이 발생합니다.

# 피해야 할 파일 이름들
requests.py     # requests 라이브러리와 충돌
pandas.py       # pandas와 충돌
numpy.py        # numpy와 충돌
os.py           # 표준 라이브러리와 충돌

파일 이름을 my_requests.py, data_handler.py 같이 라이브러리 이름과 겹치지 않게 지정하는 것을 권장합니다.


원인 5 — 직접 만든 모듈 경로 문제

같은 프로젝트 안의 파일을 import할 때 오류 발생

직접 만든 Python 파일을 다른 파일에서 import할 때도 ModuleNotFoundError가 발생할 수 있습니다.

프로젝트/
├── main.py
└── utils/
    └── helper.py

# main.py에서 아래처럼 import하면 오류 발생 가능
import helper  # ModuleNotFoundError

해결 방법 1 — 상대 경로 import 사용

# main.py
from utils.helper import my_function

해결 방법 2 — __init__.py 파일 추가

utils 폴더 안에 빈 __init__.py 파일을 만들면 Python이 해당 폴더를 패키지로 인식합니다.

프로젝트/
├── main.py
└── utils/
    ├── __init__.py   ← 이 파일 추가
    └── helper.py

# 이제 아래처럼 import 가능
from utils.helper import my_function


해결 방법 3 — sys.path에 경로 추가

임시로 경로를 추가해야 할 경우 사용합니다.

import sys
from pathlib import Path

# 프로젝트 루트를 Python 경로에 추가
sys.path.insert(0, str(Path(__file__).parent.parent))

from utils.helper import my_function

빠른 진단 체크리스트

오류가 발생했을 때 순서대로 확인하면 대부분 해결됩니다.

# 1단계 — 현재 Python 경로 확인
where python       # Windows
which python3      # macOS / Linux

# 2단계 — 가상환경 활성화 여부 확인 (프롬프트 앞 (venv) 표시 확인)

# 3단계 — 설치 여부 확인
pip list | grep pandas    # Windows PowerShell
pip list | grep pandas    # macOS / Linux

# 4단계 — 동일 환경에 설치
python -m pip install 패키지명

# 5단계 — VS Code 인터프리터 확인
# Ctrl+Shift+P → Python: Select Interpreter

마무리

✅ ModuleNotFoundError 해결 체크리스트

  1. pip list 로 설치 여부 먼저 확인
  2. 가상환경 활성화 여부 확인 — 프롬프트 앞 (venv) 표시 체크
  3. python -m pip install 로 설치 — pip과 python이 같은 환경을 가리키도록 보장
  4. VS Code 인터프리터 를 가상환경 경로로 재설정
  5. 파일 이름 이 라이브러리 이름과 겹치지 않는지 확인
  6. 직접 만든 모듈 은 __init__.py + 상대 경로 import로 해결
  7. pip 이름과 import 이름 이 다른 라이브러리는 별도 확인

ModuleNotFoundError는 무서운 오류가 아닙니다. 원인을 알면 대부분 1~2분 안에 해결됩니다. 위 체크리스트를 북마크해 두고 오류가 날 때마다 순서대로 확인해 보십시오.



댓글

댓글 쓰기

이 블로그의 인기 게시물

1.Python 설치부터 실행까지 10분 만에 끝내기 — 초보자도 바로 따라 하는 완벽 가이드

이미지
프로그래밍을 처음 시작하기로 결심한 날, 많은 분들이 유튜브를 켜고 이렇게 검색합니다. "파이썬 설치 방법." 영상을 따라가다 보면 어느 순간 화면 속 강사의 컴퓨터와 내 컴퓨터가 달라지기 시작합니다. "명령어를 찾을 수 없습니다", "PATH가 설정되지 않았습니다" 같은 오류 메시지가 등장하고, 결국 설치도 못 한 채 탭을 닫아버리게 됩니다. 이 글은 바로 그 지점을 해결하기 위해 쓰였습니다. 설치 과정에서 실제로 막히는 이유, 놓치기 쉬운 체크박스 한 칸의 의미, 그리고 첫 코드를 실행하는 순간까지 — 군더더기 없이 안내해 드리겠습니다. 저도 처음 설치때 1시간을 소비 했습니다.이제 해매지 마세요~!!  Python이 실제로 하는 일 — 번역가 비유로 이해하기 Python을 설치하기 전에, Python이 무엇인지 정확히 이해하면 이후 과정이 훨씬 자연스러워집니다. 컴퓨터는 본래 0과 1, 즉 기계어만 이해합니다. 사람이 "파일을 열어줘"라고 말해도 컴퓨터는 알아듣지 못합니다. Python은 바로 이 간극을 메우는 번역가 역할을 합니다. 우리가 사람에게 말하듯 작성한 코드를 컴퓨터가 이해할 수 있는 언어로 변환해 주는 것입니다. 여기서 핵심이 있습니다. 번역가가 없으면 대화가 불가능합니다. Python을 설치한다는 것은 곧 이 번역가를 내 컴퓨터에 고용하는 일입니다. 설치가 완료된 순간부터 여러분의 컴퓨터는 Python이라는 언어를 이해하기 시작합니다. Python을 선택해야 하는 이유 문법이 자연어에 가깝습니다 — if 날씨 == "맑음": 나가기() 처럼, 코드가 한국어 문장 구조와 유사합니다. 범용성이 압도적입니다 — 데이터 분석, 웹 개발, 자동화, AI 모델 구축까지 하나의 언어로 가능합니다. 생태계가 방대합니다 — 전 세계 개발자들이 만든 50만 개 이상의 라이브러리가 무료로 제공됩니다. 취업 시장에서 가장 수요가 높습니다 ...
자세한 내용 보기

30.Python pyautogui로 마우스와 키보드 자동화하기: VSCode 실전 가이드

이미지
 저도 처음에 PATH에서 막혔는데, 매일 반복되는 사내 시스템 클릭 작업을 자동화해보려고 pyautogui 를 설치했지만 VSCode에서 실행할 때마다 "No module named 'pyautogui'"라는 오류만 계속 나왔던 기억이 있습니다. 분명 터미널에서는 설치가 잘 됐다고 나왔는데, 알고 보니 VSCode가 바라보고 있던 Python 인터프리터 경로와 제가 패키지를 설치한 경로가 서로 달랐던 것이 원인이었습니다. 인터프리터를 올바르게 맞춰주고 나서야 마우스가 제 손을 대신해 화면을 클릭하고 키보드를 두드리는 신기한 광경을 볼 수 있었습니다. 이번 글에서는 그때의 시행착오를 바탕으로, VSCode 환경에서 Python pyautogui를 활용해 마우스와 키보드를 자동화하는 방법을 정리해보려 합니다. pyautogui란 무엇인가 마우스와 키보드를 코드로 제어하는 라이브러리 pyautogui 는 Python 코드로 마우스 움직임과 클릭, 키보드 입력을 프로그래밍적으로 제어할 수 있게 해주는 GUI 자동화 라이브러리입니다. 웹 브라우저나 애플리케이션 내부 요소를 직접 다루는 Selenium과 달리, pyautogui는 화면 좌표와 픽셀을 기준으로 동작하기 때문에 특정 프로그램에 국한되지 않고 컴퓨터 화면에서 벌어지는 거의 모든 작업을 자동화할 수 있습니다. 비유하자면 pyautogui는 마치 컴퓨터 앞에 보이지 않는 손 하나를 앉혀두는 것과 같습니다. 이 손은 사람이 시키는 대로 정확한 좌표를 클릭하고, 정해진 문장을 타이핑하며, 화면 속 특정 이미지를 찾아내기까지 하는데, 사람과 다른 점은 지치지 않고 똑같은 작업을 몇 번이고 정확하게 반복한다는 것입니다. pyautogui가 유용한 대표적인 상황 반복적인 클릭 작업이 많은 사내 시스템 업무 자동화 특정 시간마다 실행해야 하는 프로그램 작업 자동화 게임이나 소프트웨어 테스트 시 반복 입력 시뮬레이션 화면 캡처와 이미지 인식을 결합한 자동 작업 흐름 구성 매크로 프로그램을 대...
자세한 내용 보기

29.Python subprocess로 외부 명령어 실행하기: VSCode 실전 활용법

이미지
저도 처음에는 회사에서 매일 반복하던 번거로운 서버 배포 작업을 자동화해 보려고, 파이썬 스크립트 안에 깃( git ) 명령어를 넣어 실행하는 코드를 짰던 것이 시작이었습니다. 분명 내 터미널에 직접 입력할 때는 잘만 되던 명령어가, 파이썬 코드로 실행하니 자꾸 FileNotFoundError 만 뱉어내서 도대체 뭐가 문제인지 몇 시간이나 소스 코드 이 줄 저 줄을 뜯어고치며 밤새 삽질을 했습니다. 알고 보니 코드가 아니라 VS Code가 명령 프로그램의 위치를 찾지 못하는 'PATH 환경변수' 문제였죠. 실행 경로를 명시해 주자마자 스크립트가 배포 작업을 알아서 척척 단 5초 만에 끝내는 걸 보고 , 저는 이 파이썬 자동화의 강력함에 완전히 매료되었습니다. 이번 글에서는 그때의 시행착오를 바탕으로 subprocess 를 활용해 외부 명령어를 안전하게 제어하는 방법을 정리해 보겠습니다. Python 코드 안에서 터미널 명령어를 직접 실행하고 싶었던 적이 있으신가요? 예를 들어 git , ffmpeg , curl 같은 외부 프로그램을 Python 스크립트 안에서 자동으로 호출하고 그 결과를 받아와야 하는 경우가 생각보다 자주 발생합니다. 이럴 때 필요한 것이 바로 subprocess 모듈이며, 이를 활용하면 Python이 마치 터미널을 대신 조작하는 것처럼 외부 프로그램을 자유자재로 실행할 수 있습니다. 이번 글에서는 VSCode 환경에서 Python subprocess를 활용해 외부 명령어를 실행하고 결과를 처리하는 방법을 실전 예제와 함께 정리해보겠습니다. subprocess란 무엇인가 Python에서 외부 프로세스를 실행하는 표준 모듈 subprocess 는 Python 표준 라이브러리에 내장된 모듈로, Python 코드 안에서 운영체제의 명령어나 다른 프로그램을 새로운 프로세스로 실행할 수 있게 해줍니다. 쉽게 말해 여러분이 평소 터미널에 직접 타이핑하던 명령어를, Python 코드가 대신 입력해주고 그 결과까지 받아와주는 것이...
자세한 내용 보기