파이썬 모듈 없음 오류 (ModuleNotFoundError: No module named) 진짜 원인과 해결

파이썬 모듈 없음 오류 (ModuleNotFoundError: No module named) 진짜 원인과 해결

방금 터미널에서 pip install requests를 쳤고, "Successfully installed requests"까지 두 눈으로 봤다. 그런데 python app.py를 실행하자 대뜸 ModuleNotFoundError: No module named 'requests'가 뜬다. 분명 설치했는데 없다니, 파이썬이 거짓말을 하는 것 같다. 이 글은 그 억울한 순간의 진짜 범인을 잡는 이야기다. 결론부터 말하면 대부분은 "설치가 안 된 것"이 아니라 "설치한 파이썬과 실행하는 파이썬이 서로 다른 것"이다. 왜 그런지, 그리고 딱 세 줄로 범인을 특정하는 방법과 상황별 해결까지 깊게 파고든다.

파이썬 모듈 없음 오류

 

이 에러는 파이썬을 처음 배울 때도, 몇 년을 쓴 뒤에도 만난다. 그런데 검색해서 나오는 "pip install 다시 하세요"는 절반의 경우 아무 소용이 없다. 같은 잘못된 파이썬에 또 설치할 뿐이기 때문이다. 그래서 이 글은 "무엇을 설치하라"가 아니라 "누가 이 코드를 실행하고 있는가"를 먼저 묻는다.

이 글에서 짚는 것

 

01왜 "설치했는데 없다"고 하는가 — 파이썬이 여러 대라는 사실

02단 세 줄로 범인을 특정하는 진단법

03진짜 원인 여섯 가지와 각각의 신호

04증상에서 해결로 가는 진단 흐름도

05흔히 하는 잘못된 처방과 왜 실패하는가

---

🧭 "설치했는데 없다"는 말의 진짜 뜻

핵심 오해부터 풀자. 우리는 은연중에 컴퓨터에 파이썬이 한 대만 있다고 생각한다. 하지만 실제로는 여러 대가 공존하는 경우가 대부분이다. 운영체제에 기본 내장된 시스템 파이썬, 직접 설치한 3.11과 3.12, 아나콘다가 깔아 둔 파이썬, 그리고 프로젝트마다 만든 가상환경(venv) 속 파이썬까지. 각각은 자기만의 site-packages 폴더, 즉 "설치된 라이브러리 창고"를 따로 가진다.

 

여기서 문제가 생긴다. pip는 "어딘가의 파이썬"에 라이브러리를 넣고, python 명령은 "또 다른 파이썬"을 실행할 수 있다. 그러면 pip는 A 파이썬의 창고에 requests를 넣었는데, 정작 코드는 requests가 없는 B 파이썬으로 돌아간다. B 입장에서는 정말로 없으니 거짓말이 아니라 사실을 말한 것이다.

한 문장 요약

ModuleNotFoundError는 "이 라이브러리가 세상에 없다"가 아니라 "지금 이 코드를 실행하는 바로 그 파이썬의 창고에 없다"는 뜻이다. 그래서 질문은 "설치했나?"가 아니라 "누가 실행 중이고, 그가 어디를 뒤졌나?"가 되어야 한다.

파이썬이 모듈을 찾는 과정은 단순하다. import requests를 만나면, 파이썬은 sys.path라는 목록에 적힌 폴더들을 위에서부터 훑으며 requests라는 이름의 모듈이나 패키지를 찾는다. 맨 위에는 보통 스크립트가 있는 현재 폴더가, 그다음에 표준 라이브러리, 마지막에 site-packages(pip로 설치한 것들이 쌓이는 곳)가 온다. 이 목록 어디에도 requests가 없으면 그때 ModuleNotFoundError를 던진다. 진단이란 결국 "이 파이썬의 sys.path에 왜 그 모듈이 안 걸리는가"를 밝히는 일이다.

---

🔬 세 줄이면 범인이 드러난다

추측을 멈추고 사실을 확인하자. 아래 세 줄이면 "실행 파이썬"과 "설치 파이썬"이 어긋났는지 즉시 보인다. 실제 재현부터 보자. 흔한 상황이다.

$ pip install requests
Successfully installed requests-2.32.3
$ python app.py
Traceback (most recent call last):
  File "app.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

설치 성공 메시지와 없다는 에러가 나란히 있으니 억울할 만하다. 이제 세 줄로 캐묻는다.

# 1) 지금 코드를 실행하는 파이썬은 누구인가
$ python -c "import sys; print(sys.executable)"
C:\Python39\python.exe            # ← 3.9가 실행 중

# 2) pip는 어느 파이썬에 붙어 있는가
$ pip -V
pip 24.0 from C:\...\Python311\site-packages\pip (python 3.11)
                                  # ← 설치는 3.11에 됐다!

# 3) 실행 파이썬과 '같은' 곳에 설치
$ python -m pip install requests

범인이 잡혔다. 실행은 3.9인데 설치는 3.11에 됐다. 서로 다른 창고를 보고 있었던 것이다. 3번 줄이 이 문제의 결정적 한 방이다. python -m pip는 "지금 python이 가리키는 바로 그 파이썬의 pip"를 실행하라는 뜻이라, 설치와 실행이 물리적으로 같은 파이썬에서 일어난다. 이 습관 하나만 들여도 이 에러의 상당수가 사라진다.

왜 python -m pip 인가

그냥 pip는 시스템이 PATH에서 먼저 찾은 아무 pip일 수 있다. 반면 python -m pip는 방금 코드를 실행한 그 python에게 "네 안의 pip 모듈을 돌려라"라고 시키는 것이라, 설치 대상이 실행 대상과 어긋날 수가 없다. 윈도우라면 특정 버전을 콕 집어 py -3.11 -m pip install 처럼 런처를 쓸 수도 있다.

---

🧩 진짜 원인 여섯 가지

세 줄 진단으로 대부분 끝나지만, 신호를 알아 두면 더 빨리 좁힌다. 실무에서 만나는 순서대로 정리했다.

원인 1 — 설치·실행 파이썬 불일치 (압도적 1위)

위에서 본 그 상황이다. 시스템 파이썬과 직접 설치한 버전, 아나콘다, 여러 마이너 버전이 섞여 pip와 python이 다른 곳을 본다. 신호는 pip -V의 경로와 sys.executable 경로가 서로 다르다는 것. 해결은 python -m pip install 로 통일.

원인 2 — 가상환경(venv)을 안 켰다

프로젝트 venv에 라이브러리를 깔아 놓고, 정작 실행할 때 activate를 잊어 시스템 파이썬으로 돌린 경우다. 반대로 venv를 켠 채 다른 창에서 시스템 pip로 설치해도 어긋난다. 신호는 터미널 프롬프트 앞에 (.venv) 표시가 없다는 것.

원인 3 — pip 이름과 import 이름이 다르다

설치·실행 파이썬이 같은데도 없다고 한다면 이걸 의심한다. beautifulsoup4를 깔고 import beautifulsoup4를 하면 당연히 없다. 실제 모듈 이름은 bs4다. 이런 이름 불일치 패키지가 꽤 있다(아래 표).

원인 4 — 내 파일·폴더가 패키지 이름을 가로챈다

연습하려고 파일을 requests.py나 email.py처럼 표준·설치 패키지와 같은 이름으로 저장하면, import가 진짜 패키지 대신 내 파일을 집어 온다. 그 안에 원하는 함수가 없으니 AttributeError나 하위 모듈 ModuleNotFoundError로 번진다. 파일을 지운 뒤 남은 __pycache__의 .pyc 잔재가 계속 잡히기도 한다.

원인 5 — 노트북·에디터의 파이썬이 터미널과 다르다

주피터 노트북의 커널, VS Code 우측 하단의 인터프리터가 터미널에서 쓰던 파이썬과 다른 경우다. 터미널에선 되는데 노트북에선 없다고 하면 십중팔구 이것이다. 커널·인터프리터를 pip를 실행한 그 파이썬으로 맞춰야 한다.

원인 6 — 내가 만든 패키지의 구조·경로 문제

외부 라이브러리가 아니라 직접 만든 모듈을 못 찾는 경우다. 실행 위치가 프로젝트 루트가 아니거나, 폴더가 sys.path에 없거나, 하위 폴더를 패키지로 인식시키는 구성이 어긋난 것이다. 이때는 pip가 아니라 실행 디렉터리와 임포트 경로를 손봐야 한다.

---

📛 설치 이름과 import 이름이 다른 단골들

원인 3에 해당하는, 헷갈리기로 유명한 패키지들이다. 왼쪽으로 설치하고 오른쪽으로 불러와야 한다. 이 표만 알아도 "분명 깔았는데 없다"의 한 갈래가 통째로 사라진다.

pip install (설치 이름)	import (실제 모듈 이름)	용도
beautifulsoup4	bs4	HTML 파싱
opencv-python	cv2	이미지·영상 처리
Pillow	PIL	이미지 라이브러리
scikit-learn	sklearn	머신러닝
PyYAML	yaml	YAML 파싱
python-dateutil	dateutil	날짜 처리
python-dotenv	dotenv	환경변수 로딩

이름을 확인하는 확실한 방법이 있다. pip show 패키지이름을 치면 그 패키지의 정보가 나오는데, 여기서 실제 import 이름은 공식 문서나 PyPI 페이지의 사용 예시를 보는 게 가장 정확하다. 그리고 pip list로 지금 이 파이썬에 실제로 뭐가 깔렸는지 눈으로 확인하면, 설치 자체가 안 됐는지 이름을 잘못 부른 것인지 단번에 갈린다.

---

🌳 증상에서 해결로 — 진단 흐름

지금까지의 원인을 하나의 흐름으로 이었다. 위에서부터 예/아니오로 따라가면 자신의 상황에 맞는 해결로 도착한다.

ModuleNotFoundError: No module named 'X'

▼

① X를 애초에 설치한 적이 있나?

없다 → python -m pip install X 로 설치하고 끝.

▼ 설치했다는데도 뜬다면

② 설치 이름과 import 이름이 같은가?

다르다(bs4·cv2·PIL 등) → 올바른 import 이름으로 수정.

▼ 이름도 맞다면

③ pip -V 경로와 sys.executable이 같은가?

다르다 → 설치·실행 파이썬 불일치. python -m pip install X 로 통일(또는 venv 활성화).

▼ 같은 파이썬인데도 뜬다면

④ 내 파일·폴더 이름이 그 패키지와 겹치나?

그렇다(requests.py 등) → 파일명 변경 + __pycache__ 삭제. 아니면 내 패키지 구조·실행 위치·sys.path 점검.

이 흐름의 미덕은 순서에 있다. 무작정 재설치부터 하지 않고, "설치 여부 → 이름 → 파이썬 일치 → 이름 충돌 → 경로" 순으로 값싼 확인부터 배치했다. 대부분은 ①∼③에서 끝난다.

---

🛠 상황별 해결과 트레이드오프

해결 방법과 언제 쓰나

 

01python -m pip install X — 설치와 실행 파이썬을 강제로 일치. 거의 모든 상황의 기본기. 단점은 거의 없어 첫 시도로 권장.

02프로젝트마다 venv 만들기 — 라이브러리를 프로젝트별로 격리해 충돌을 원천 차단. 실행 전 activate만 잊지 않으면 가장 깔끔. 매 프로젝트 생성·관리 수고가 트레이드오프.

03IDE·노트북 인터프리터 맞추기 — VS Code는 우측 하단, 주피터는 커널 메뉴에서 pip를 실행한 그 파이썬 선택. 터미널만 되고 에디터는 안 될 때의 정답.

04노트북 안에서 설치할 땐 %pip install X — 매직 명령이라 그 커널의 파이썬에 정확히 설치된다. 셀에서 !pip(느낌표)는 다른 파이썬에 갈 수 있어 피한다.

가장 권할 만한 습관은 프로젝트마다 venv를 쓰는 것이다. 아래처럼 만들고 켜면, 그 순간부터 python과 pip가 모두 그 환경 안의 파이썬을 가리켜 불일치 자체가 생기지 않는다.

# 가상환경 만들고 켜기 (Windows PowerShell)
$ py -m venv .venv
$ .venv\Scripts\Activate.ps1
(.venv) $ python -m pip install requests   # 설치·실행이 같은 환경

# macOS / Linux
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install requests

프롬프트 앞에 붙은 (.venv) 표시가 "지금 이 환경이 켜져 있다"는 신호다. 이 표시가 없는데 라이브러리가 안 잡히면, 십중팔구 environment를 안 켠 것이다. 원인 4(파일명 충돌)라면 해결은 코드가 아니라 파일 이름에 있다. 표준·설치 패키지와 같은 이름의 로컬 파일을 다른 이름으로 바꾸고, 옆에 생긴 pycache 폴더와 .pyc 잔재를 지운 뒤 다시 실행하면 된다.

---

🚫 이렇게 고치면 안 된다 — 흔한 오답 노트

검색하면 자주 보이지만, 문제를 가리거나 더 키우는 처방들이다. 왜 나쁜지까지 알아야 다시 안 밟는다.

✗ 같은 pip로 그냥 재설치 반복

불일치가 원인이면, 같은 잘못된 파이썬에 몇 번을 더 깔아도 실행 파이썬 창고는 그대로 비어 있다. 재설치 전에 pip -V와 sys.executable부터 맞춰야 한다.

✗ 코드 맨 위에 sys.path.append로 강제 삽입

특정 폴더를 sys.path에 억지로 끼워 넣어 그 순간만 넘기는 방식이다. 경로가 하드코딩돼 내 컴퓨터에서만 돌아가고, 협업자·배포 환경에서 그대로 깨진다. 근본 원인(파이썬 불일치·환경)을 덮을 뿐이다.

✗ sudo pip install / 관리자 권한으로 전역 설치

시스템 파이썬을 건드리면 운영체제가 쓰는 파이썬 환경을 오염시켜 다른 프로그램이 깨질 수 있다. 권한으로 밀어붙이지 말고, 사용자 환경이나 venv에 설치하는 게 안전하다.

✗ 파이썬을 지웠다 다시 깔기

재설치는 시간만 잡아먹고 불일치를 그대로 둔 채 오히려 파이썬을 하나 더 늘리는 결과가 되기 쉽다. 진단 세 줄이면 몇 초에 끝날 문제를 크게 키우는 셈이다.

---

💬 자주 묻는 질문

Q1ModuleNotFoundError와 ImportError는 뭐가 다른가요?

ModuleNotFoundError는 ImportError의 한 종류(하위 클래스)입니다. 파이썬 3.6부터 "모듈 자체를 못 찾은" 경우를 더 명확히 알려 주려고 세분화됐죠. 모듈은 찾았는데 그 안의 특정 이름을 못 가져오면 "ImportError: cannot import name ..."이 뜹니다. 즉 없는 게 모듈 전체인지, 모듈 안의 함수·클래스인지가 갈립니다.

Q2터미널에선 되는데 주피터 노트북에서만 없다고 해요.

노트북 커널의 파이썬이 터미널의 파이썬과 다른 겁니다. 노트북 셀에서 import sys; print(sys.executable)을 찍어 경로를 확인하고, 그 커널 안에 설치하려면 %pip install 패키지 매직 명령을 쓰세요. 셀의 !pip(느낌표)는 엉뚱한 파이썬으로 갈 수 있어 %pip가 더 안전합니다.

Q3분명 pip list에 있는데도 없다고 합니다.

그 pip list와 코드를 실행하는 파이썬이 서로 다른 파이썬일 가능성이 높습니다. python -m pip list처럼 실행 파이썬을 명시해 목록을 뽑아 비교해 보세요. 목록에서 사라졌다면 원인은 명확히 파이썬 불일치입니다. 목록엔 있는데 안 되면 import 이름 충돌이나 로컬 파일 가로채기를 봅니다.

Q4파이썬 3.11부터 에러가 더 친절해졌다던데요?

맞습니다. 파이썬 3.10부터 오타가 났을 때 "이걸 말한 건가요?"식 제안이 붙기 시작했고, 3.11부터는 트레이스백이 문제 지점을 화살표로 더 정밀하게 가리키며, 3.12에서는 빠뜨린 표준 모듈에 대해 "sys를 import 하려던 것 아닌가요?"처럼 제안이 더 넓어졌습니다. 다만 ModuleNotFoundError 자체는 여전히 "없다"는 사실만 알려 주므로, 원인 규명은 이 글의 진단 세 줄이 담당합니다.

---

📌 정리하며

ModuleNotFoundError는 "이 라이브러리가 세상에 없다"가 아니라 "지금 이 코드를 실행하는 파이썬의 창고에 없다"는 신고다. 그래서 재설치를 반복하기 전에, 누가 실행 중인지(sys.executable)와 pip가 어디에 붙었는지(pip -V)를 먼저 맞춰 보는 것이 가장 빠른 길이다.

 

핵심 습관을 세 가지로 남긴다.

🧩 설치는 언제나 python -m pip install 로 한다. 실행하는 파이썬과 설치하는 파이썬을 물리적으로 묶어, 이 에러의 최대 원인을 원천 차단한다.

📦 프로젝트마다 venv를 만들고 켠 뒤 작업한다. 프롬프트의 (.venv) 표시를 매번 확인하면 환경 불일치를 눈으로 막을 수 있다.

🔤 안 될 땐 이름부터 의심한다. bs4·cv2·PIL·sklearn처럼 설치 이름과 import 이름이 다른 단골을 기억하고, pip list로 실제 설치 목록을 눈으로 확인한다.

모듈 없음 오류 진단 체크리스트

 

01python -c "import sys; print(sys.executable)"로 실행 파이썬 확인.

02pip -V 경로와 위 경로가 같은지 대조.

03어긋났으면 python -m pip install 패키지 로 통일.

04import 이름이 설치 이름과 다른지(bs4·cv2·PIL 등) 확인.

05venv 프롬프트(.venv) 표시 여부·활성화 상태 점검.

06로컬 파일명이 패키지명과 겹치지 않는지 + __pycache__ 정리.

---

본 글은 파이썬 ModuleNotFoundError의 일반적 원인과 진단·해결 방법을 정리한 자료다. 환경 설정 변경이나 패키지 설치는 프로젝트 상황을 확인한 뒤 신중히 적용한다.

 

#파이썬 #Python #ModuleNotFoundError #Nomodulenamed #파이썬에러 #pip #가상환경 #venv #파이썬모듈 #ImportError #파이썬설치 #파이썬초보 #파이썬디버깅 #코딩 #프로그래밍