파이썬 ModuleNotFoundError 해결하는 5가지 방법

by

분명히 pip install로 설치했는데 실행하면 ModuleNotFoundError가 뜹니다. 설치를 다시 해봐도 “already satisfied”라는 메시지만 나오고 오류는 그대로입니다.

이 오류로 30분씩 헤매는 경우가 흔합니다. 원인이 하나가 아니라서 그렇습니다. 설치가 안 된 게 아니라 설치한 곳과 실행하는 곳이 다른 경우가 대부분입니다.

아래 다섯 가지를 순서대로 확인하면 거의 모든 경우가 해결됩니다. 위쪽일수록 흔한 원인입니다.

Traceback (most recent call last):
  File "main.py", line 1, in <module>
    import requests
ModuleNotFoundError: No module named 'requests'

1. 파이썬이 여러 개 설치돼 있는 경우

가장 흔한 원인입니다. 시스템에 파이썬이 두 개 이상 있으면 pip가 A에 설치하고 python은 B로 실행되는 일이 생깁니다.

먼저 지금 실행되는 파이썬이 어느 것인지 확인합니다.

# 지금 실행되는 파이썬이 어느 것인지 확인
python -c "import sys; print(sys.executable)"

# 그 파이썬에 설치된 패키지 목록
python -m pip list

출력된 경로를 보고, 설치했다고 생각한 파이썬과 같은지 확인합니다. 다르면 이게 원인입니다.

2. pip 대신 python -m pip 쓰기

1번 문제를 근본적으로 막는 방법입니다. python -m pip는 지금 실행 중인 그 파이썬에 설치하도록 강제합니다.

# 나쁜 예 — 어느 파이썬에 설치되는지 알 수 없음
pip install requests

# 좋은 예 — 지금 쓰는 파이썬에 확실히 설치
python -m pip install requests

습관을 이렇게 바꾸면 파이썬이 몇 개 깔려 있든 어긋날 일이 없습니다.

3. 가상환경이 활성화되지 않은 경우

가상환경을 만들어두고 활성화를 잊은 채 실행하면, 전역 파이썬이 돌기 때문에 가상환경에 설치한 패키지를 못 찾습니다.

# 가상환경 만들기
python -m venv .venv

# 활성화 (윈도우 PowerShell)
.venv\Scripts\Activate.ps1

# 활성화 (맥 / 리눅스)
source .venv/bin/activate

# 활성화된 상태에서 설치
python -m pip install requests

활성화되면 터미널 프롬프트 앞에 (.venv)가 붙습니다. 이게 보이지 않으면 활성화가 안 된 것입니다.

VS Code에서는 터미널이 아니라 편집기 우측 하단의 인터프리터 선택이 따로 있습니다. 터미널에서는 되는데 실행 버튼으로는 안 된다면 이쪽을 확인하세요.

4. 패키지 이름과 모듈 이름이 다른 경우

설치할 때 쓰는 이름과 코드에서 import하는 이름이 다른 패키지가 있습니다. 이름이 같을 거라고 생각하면 계속 헤매게 됩니다.

pip install 이름import 이름용도
beautifulsoup4bs4HTML 파싱
pillowPIL이미지 처리
opencv-pythoncv2영상 처리
python-dotenvdotenv환경변수 로딩
pyyamlyamlYAML 파싱

오류 메시지에 나온 이름으로 검색해서 실제 설치 명령을 확인하는 편이 빠릅니다.

5. 내가 만든 모듈을 못 찾는 경우

외부 패키지가 아니라 직접 만든 파일을 import할 때 나는 오류입니다. 원인은 두 가지입니다.

  1. 실행 위치가 달라서 파이썬이 그 폴더를 못 보는 경우
  2. 패키지 폴더에 __init__.py가 없는 경우

파이썬이 어느 경로를 뒤지는지 직접 확인할 수 있습니다.

import sys
print("\n".join(sys.path))

여기 내 프로젝트 폴더가 없다면 파이썬은 그 폴더를 아예 보지 않습니다. 프로젝트 최상위에서 실행하거나 구조를 아래처럼 잡습니다.

myproject/
    main.py
    utils/
        __init__.py      # 이 파일이 있어야 패키지로 인식
        helper.py

순서대로 확인하는 체크리스트

  • python -c "import sys; print(sys.executable)" 로 실행 중인 파이썬 확인
  • 설치는 python -m pip install 로
  • 가상환경 프롬프트에 (.venv) 표시가 있는지 확인
  • 패키지 이름과 import 이름이 다른지 검색
  • 내 모듈이면 sys.path와 __init__.py 확인

주의할 점

  • 오류가 난다고 pip install --force-reinstall부터 하지 않습니다. 원인이 경로 문제면 아무 소용이 없고 시간만 걸립니다.
  • sudo pip install이나 관리자 권한 설치는 전역을 오염시켜 나중에 더 꼬입니다. 가상환경을 쓰는 편이 안전합니다.
  • 가상환경 폴더(.venv)는 .gitignore에 넣습니다. 통째로 커밋하면 저장소가 무거워지고 다른 PC에서 동작하지도 않습니다.

마무리

이 오류를 만나면 재설치부터 하지 말고 sys.executable을 먼저 찍어보세요. 대부분 거기서 원인이 드러납니다.

다음 글에서는 파이썬으로 오래된 파일을 자동으로 삭제하고 백업하는 방법을 다루겠습니다.

Leave a Comment