파이썬 ModuleNotFoundError 해결법: 원인별 점검 순서

파이썬 ModuleNotFoundError는 일부 환경에서는 "설치는 했는데 실행하는 파이썬이 다른 곳을 보고 있어서" 발생하는 오류입니다. 이 글은 코드를 처음 만지는 분도 원인을 하나씩 좁혀갈 수 있게, 확인 순서와 해결법을 정리합니다.

같은 컴퓨터 안에 파이썬이 여러 개 깔려 있거나, 가상환경이 켜져 있지 않은 상태에서 pip를 쓰면 이 오류가 자주 납니다. 무작정 재설치를 반복하기 쉬운데, 실제로는 명령어 한 줄로 위치만 맞춰주면 끝나는 경우가 많습니다.

목차

1. 이 에러가 정확히 무슨 뜻인가
2. 원인부터 좁히는 4단계 점검 순서
3. 그래도 안 될 때 확인할 것
4. 다시 안 겪으려면 챙길 습관
5. 변경이 오히려 상황을 악화시켰을 때 되돌리는 법

이 에러가 정확히 무슨 뜻인가

ModuleNotFoundError는 파이썬이 코드에서 부른 모듈(부품)을 찾지 못했을 때 뜨는 오류입니다. 여기서 "모듈"은 다른 사람이 만들어 둔 코드 묶음이라고 보면 됩니다. 예를 들어 import pandas라고 썼는데 pandas라는 부품이 지금 실행 중인 파이썬에 설치돼 있지 않으면 이 에러가 납니다.

에러 메시지는 보통 이렇게 생겼습니다.

ModuleNotFoundError: No module named 'pandas'

여기서 따옴표 안 이름(pandas)이 파이썬이 찾고 있는 부품 이름입니다. 이 이름을 기억해 두면 뒤에 나올 명령어에 그대로 넣게 됩니다.

핵심은 두 가지입니다.

• 그 부품이 정말 설치돼 있는가
• 설치돼 있다면, 지금 실행 중인 파이썬이 그걸 볼 수 있는 위치에 있는가

초보자가 겪는 문제의 환경에 따라은 두 번째, 즉 "위치 어긋남" 문제입니다.

원인부터 좁히는 4단계 점검 순서

해결법으로 바로 뛰어들기 전에, 어떤 원인인지부터 좁히는 게 훨씬 빠릅니다. 아래 순서대로 확인하세요.

단계	확인 내용	왜 필요한가
1	모듈 이름 오타	대소문자·철자 하나만 틀려도 에러
2	설치 여부	진짜로 안 깔렸을 수 있음
3	파이썬 위치와 pip 위치 일치	일부 환경에서는 원인
4	가상환경 활성화 상태	프로젝트별로 다른 환경 사용 시

터미널(검은 화면에 명령어를 입력하는 프로그램)에서 아래 명령어로 지금 상황을 확인할 수 있습니다.

python --version
pip --version
pip list

• python --version: 지금 쓰는 파이썬 버전
• pip --version: pip가 어느 파이썬에 붙어 있는지 경로 표시
• pip list: 지금 파이썬에 설치된 부품 목록

pip --version이 알려주는 경로와 python --version이 실제로 실행하는 파이썬 경로가 다르다면, 그게 바로 원인입니다.

해결법 1: 설치 명령어를 파이썬에 직접 붙여 쓰기

가장 확실한 해결법은 pip install ○○ 대신 python -m pip install ○○ 을 쓰는 것입니다. 이 방식은 "지금 이 파이썬에게 직접 부품을 설치해달라"고 부탁하는 명령이라, pip 경로가 꼬여 있어도 안전합니다.

python -m pip install pandas

이 명령은 "현재 python 명령이 가리키는 파이썬에 pandas를 설치하라"는 뜻입니다. 설치가 끝난 뒤 같은 터미널에서 python 명령으로 코드를 실행하면 일부 환경에서는 해결됩니다.

💡 윈도우에서 python이 안 먹히면 py -m pip install pandas로 바꿔서 시도해보세요. py는 윈도우용 파이썬 실행기입니다.

해결법 2: 파이썬이 여러 개 깔렸을 때 정리하기

한 컴퓨터에 파이썬 3.10, 3.11, 3.12가 동시에 깔려 있는 경우가 흔합니다. 이때 pip가 A 파이썬에 설치하고, python 명령은 B 파이썬을 실행하면 당연히 부품을 못 찾습니다.

확인 방법은 아래와 같습니다.

python -c "import sys; print(sys.executable)"

이 명령은 "지금 실행되는 파이썬이 정확히 어느 파일인가"를 알려줍니다. 결과로 나온 경로를 기억해 두세요. 그 경로 뒤에 -m pip install을 붙여 쓰면 오류가 사라집니다.

예를 들어 결과가 /usr/local/bin/python3.11이라면:

/usr/local/bin/python3.11 -m pip install pandas

경로가 길어서 불편하지만, 파이썬과 pip를 강제로 짝지어주는 가장 확실한 방법입니다.

해결법 3: 가상환경 활성화 확인

가상환경은 프로젝트마다 부품 창고를 따로 두는 기능입니다. 프로젝트 A에는 pandas 1.5, 프로젝트 B에는 pandas 2.0이 필요할 때 서로 안 부딪히게 해줍니다.

문제는 가상환경을 만들어놓고 활성화하지 않은 채 pip install을 하는 경우입니다. 그러면 부품은 시스템 파이썬에 깔리고, 나중에 가상환경으로 코드를 실행하면 못 찾습니다.

가상환경을 쓰고 있다면 터미널 앞에 이런 표시가 있어야 합니다.

(venv) $
(myproject) $

괄호 안 이름이 안 보이면 가상환경이 꺼진 상태입니다. 활성화 명령은 운영체제별로 다릅니다.

환경	활성화 명령
맥/리눅스	source venv/bin/activate
윈도우 (CMD)	venv\Scripts\activate.bat
윈도우 (PowerShell)	venv\Scripts\Activate.ps1

venv 자리에는 본인이 만든 가상환경 폴더 이름을 넣습니다. 활성화한 뒤에 pip install을 다시 하세요.

해결법 4: 주피터 노트북·VS Code에서 커널이 다른 경우

주피터 노트북이나 VS Code에서 코드를 돌리는데 터미널에서 pip install이 성공했는데도 에러가 난다면, 노트북이 다른 파이썬을 쓰고 있는 것입니다.

이때는 노트북 안에서 직접 설치하는 방법이 가장 확실합니다. 노트북 셀 안에 이렇게 씁니다.

import sys
!{sys.executable} -m pip install pandas

앞에 붙은 !는 "이 줄은 터미널 명령이야"라는 표시이고, {sys.executable}은 "지금 노트북이 쓰는 파이썬의 정확한 경로"를 뜻합니다. 이 두 개를 조합하면 노트북이 실제로 쓰는 파이썬에 부품이 설치됩니다.

VS Code라면 오른쪽 위 또는 아래에 파이썬 인터프리터 선택 버튼이 있습니다. 여기서 pip install을 실행한 파이썬과 같은 것을 골라야 합니다.

해결법 5: 부품 이름과 import 이름이 다른 경우

가끔 설치할 때 쓰는 이름과 코드에서 import할 때 쓰는 이름이 다른 부품들이 있습니다. 이걸 모르면 계속 "설치했는데 왜 없다고 나오지?" 하게 됩니다.

자주 헷갈리는 것들:

설치 명령	코드에서 import
pip install beautifulsoup4	import bs4
pip install opencv-python	import cv2
pip install pillow	import PIL
pip install scikit-learn	import sklearn
pip install pyyaml	import yaml

에러 메시지에 No module named 'cv2'가 뜬다고 pip install cv2를 하면 오히려 이상한 패키지가 깔립니다. 반드시 공식 문서에서 정확한 설치 이름을 확인하세요.

해결법 6: 로컬 파일 이름과 표준 모듈이 충돌하는 경우

작업 폴더 안에 표준 모듈과 같은 이름의 파일을 만들어 두면 파이썬이 헷갈립니다. 예를 들어 random.py, email.py, json.py 같은 파일을 직접 만들어 놓고 그 폴더에서 코드를 실행하면, 파이썬이 표준 모듈 대신 내 파일을 먼저 읽어버립니다.

증상은 조금 다르게 나타나기도 합니다.

ModuleNotFoundError: No module named 'random.choice'

AttributeError가 뜨기도 합니다. 해결법은 간단합니다.

• ☐작업 폴더에서 표준 모듈과 이름이 겹치는 .py 파일 이름 변경
• ☐같은 폴더에 있는 __pycache__ 폴더 삭제
• ☐터미널 다시 열고 실행

파일명은 프로젝트 이름과 상관없는 일반명(예: random, test, email)을 피하고, my_random.py처럼 구체적으로 짓는 게 안전합니다.

해결법 7: 상대 경로·패키지 구조 문제

여러 폴더에 코드를 나눠 담기 시작하면 from utils import helper 같은 코드에서 에러가 나기 쉽습니다. 파이썬은 현재 실행 위치를 기준으로 부품을 찾는데, 그 기준이 어긋나면 못 찾습니다.

빠르게 확인할 것들:

• 부품이 들어 있는 폴더에 __init__.py 라는 빈 파일이 있는지 (신형 파이썬에서는 없어도 되지만, 안전하게 넣어두는 편이 좋습니다)
• 터미널의 현재 위치가 프로젝트 최상위 폴더인지 (pwd 또는 cd로 확인)
• 실행 시 python script.py 대신 python -m 폴더명.script로 실행해야 하는 구조인지

이 부분은 프로젝트 구조에 따라 달라서, 파이썬 공식 튜토리얼의 "Modules" 문서를 한 번 훑어보길 권합니다.

그래도 안 될 때 확인할 것

위 7가지를 다 해봤는데도 계속 같은 에러가 뜨면 아래를 순서대로 점검하세요.

현재 실행 파이썬 확인
   ↓
같은 파이썬에 설치됐는지 확인
   ↓
가상환경 켜져 있는지 확인
   ↓
에디터 인터프리터 설정 확인
   ↓
캐시(__pycache__) 삭제 후 재실행

특히 에디터(VS Code, PyCharm 등)를 껐다 켜야 인터프리터 변경이 반영되는 경우가 많습니다. 설정을 바꿨는데도 여전히 안 되면 에디터를 완전히 종료 후 다시 열어보세요.

다시 안 겪으려면 챙길 습관

같은 에러를 반복하지 않으려면 처음부터 환경을 깔끔하게 시작하는 습관이 가장 효율적입니다.

• ☐새 프로젝트마다 가상환경 만들기
• ☐부품 설치는 환경에 따라 python -m pip install 형태로
• ☐설치 후 pip freeze > requirements.txt로 목록 저장
• ☐파일 이름을 표준 모듈과 겹치지 않게 짓기
• ☐에디터의 파이썬 인터프리터를 프로젝트 가상환경으로 지정

이 다섯 가지만 지켜도 ModuleNotFoundError로 시간을 버리는 일이 크게 줄어듭니다. 처음엔 번거로워 보이지만 익숙해지면 오히려 문제가 생겼을 때 원인 추적이 훨씬 빨라집니다.

함께 보면 좋은 글

• 파이썬 pip 설치 오류 해결 7가지 — 맥·윈도우 초보용
• Zig 언어가 뭔가요 — Rust 다음 후보 5분 정리
• Go 5분 입문 — 왜 백엔드는 자꾸 Go로 가나

원인을 순서대로 격리하는 점검 흐름

앞의 7가지 해결법을 하나씩 시도하다 보면 무엇을 이미 확인했고 무엇이 남았는지 놓치기 쉽습니다. 아래 흐름은 의심 범위를 좁혀가는 순서입니다. 위에서 아래로 하나씩 내려가며, 각 단계에서 결과를 메모해 두세요.

1. 에러 메시지의 모듈 이름을 그대로 복사합니다. 오타·대소문자 여부를 이 시점에 확정합니다.
2. 터미널 한 곳만 정해서 python -c "import sys; print(sys.executable)" 결과를 적어둡니다. 이후 모든 확인은 같은 터미널에서 합니다.
3. 같은 터미널에서 python -m pip list를 실행해 해당 모듈이 목록에 있는지 봅니다. 없으면 설치 문제, 있으면 위치 문제로 분기됩니다.
4. 목록에 있는데도 에러가 난다면, 코드를 실행하는 도구(주피터·VS Code·PyCharm)가 이 터미널과 같은 파이썬을 쓰는지 확인합니다. 다르면 그게 원인입니다.
5. 목록에 없다면, 가상환경 활성화 여부부터 다시 확인한 뒤 python -m pip install로 같은 파이썬에 설치합니다.
6. 여기까지 해도 해결되지 않으면 작업 폴더 안의 파일명 충돌(해결법 6)과 패키지 구조 문제(해결법 7)를 마지막으로 봅니다.

이 순서를 지키면 "뭘 시도했는지 기억이 안 나서 처음부터 다시" 하는 상황을 피할 수 있습니다.

변경이 오히려 상황을 악화시켰을 때 되돌리는 법

설치·삭제·설정 변경을 반복하다 보면 원래 되던 것까지 안 되는 경우가 생깁니다. 이때는 되돌릴 지점을 정해두고 그 지점까지 복귀하는 편이 빠릅니다.

• 새 부품을 설치했는데 상황이 나빠졌다면, 같은 터미널에서 python -m pip uninstall 부품이름으로 방금 설치한 것을 제거합니다. 여러 개를 연달아 깔았다면 마지막에 깐 것부터 역순으로 제거하세요.
• requirements.txt를 미리 저장해 뒀다면, 가상환경을 지우고 새로 만든 뒤 python -m pip install -r requirements.txt로 이전 상태를 복원할 수 있습니다. 저장해 두지 않았다면 이번 기회에 pip freeze > requirements.txt로 지금 되는 상태를 먼저 기록해 두세요.
• 가상환경 자체가 꼬였다고 판단되면, 프로젝트 폴더의 가상환경 폴더(venv 등)를 통째로 삭제하고 새로 만드는 편이 개별 문제를 추적하는 것보다 빠릅니다. 이 경우 프로젝트 소스 코드는 건드리지 않습니다.
• 에디터의 인터프리터 설정을 바꿔서 문제가 생겼다면, 설정에서 원래 쓰던 파이썬 경로로 되돌린 뒤 에디터를 완전히 종료했다가 다시 엽니다.

되돌리기 전에 어떤 명령을 실행했는지 순서대로 적어두면 같은 시행착오를 반복하지 않습니다. 터미널 기록(history 명령)을 훑어보는 것도 도움이 됩니다.