AI 생성 이미지: 성인 개발자가 노트북에서 Python 실행 환경과 패키지 설치 경로를 대조하는 장면

파이썬 pip로 설치했는데 ModuleNotFoundError가 날 때: 실행 인터프리터와 가상환경 확인법

by

pip 설치는 끝났는데 실행할 때만 ModuleNotFoundError가 나오면, 패키지가 사라진 것보다 설치한 Python과 실행한 Python이 다른 경우를 먼저 의심해야 합니다. 먼저 실행 중인 Python의 sys.executable과 같은 실행 파일로 호출한 python -m pip --version의 경로를 비교합니다. 경로가 다르면 같은 환경에 설치되지 않은 것이므로 실행 인터프리터를 맞춘 뒤 다시 설치합니다.

1. 실행 Python과 pip 경로 확인

다음 코드를 오류가 나는 실행 경로에서 직접 실행합니다.

import sys
import subprocess

print("Python:", sys.executable)
print(subprocess.check_output(
    [sys.executable, "-m", "pip", "--version"],
    text=True,
).strip())

먼저 실행 중인 Python의 sys.executable과 같은 실행 파일로 호출한 python -m pip –version의 경로를 비교합니다. sys.executable은 현재 실행 중인 Python 인터프리터의 경로를 보여 주며, python -m pip는 지정한 Python으로 pip 모듈을 실행합니다. 따라서 별도로 pip --version을 확인하는 것보다 오류가 난 프로그램의 sys.executable을 기준으로 pip를 호출하는 편이 정확합니다.

2. venv는 실행 파일로 확인

venv는 프로젝트별 Python 인터프리터와 패키지 위치를 분리하는 환경이므로, 활성화 여부만 믿지 말고 실행 파일 경로를 확인해야 합니다. 프로젝트에서 다음처럼 환경을 만들고 그 안의 Python을 직접 사용하면 경계가 분명해집니다.

python -m venv .venv
.venv/bin/python -m pip install requests
.venv/bin/python -c "import requests; print(requests.__version__)"

Windows에서는 .venv\\Scripts\\python.exe 경로를 사용합니다. 자동화에서는 셸의 현재 활성화 상태에 기대기보다 .venv 안의 Python을 실행 명령에 직접 적는 방법이 안전합니다.

venv는 프로젝트별 Python 인터프리터와 패키지 위치를 분리하는 환경이므로, 활성화 여부만 믿지 말고 실행 파일 경로를 확인해야 합니다.

3. 설치 이름과 import 이름 구분

경로가 같은데도 모듈을 못 찾으면 설치할 때 쓰는 배포 패키지 이름과 코드에서 import하는 모듈 이름은 항상 같다고 볼 수 없습니다. importlib.metadata의 distribution 조회는 설치된 배포 패키지 기준으로 동작하므로, 설치 여부와 코드에서 불러오는 모듈을 나눠 확인하는 데 사용할 수 있습니다.

from importlib.metadata import distribution, PackageNotFoundError

try:
    dist = distribution("설치할 때 사용한 배포명")
    print(dist.metadata["Name"], dist.version)
except PackageNotFoundError:
    print("현재 실행 환경에 배포 패키지가 없습니다.")

실제 코드의 import 철자와 패키지 공식 설치 문서를 대조합니다. 다른 Python에 설치된 패키지를 찾았다고 착각하지 않도록 경로 확인을 먼저 끝내야 합니다.

4. IDE와 예약 실행기는 별도 환경

터미널에서 성공해도 IDE 실행 버튼이나 예약 실행에서 실패할 수 있습니다. 오류가 난 실행 방식에서 sys.executable, sys.path, python -m pip --version 결과를 로그로 남깁니다. 터미널과 IDE·예약 실행기의 sys.executable이 다르면 패키지를 다시 설치할 문제가 아니라 실행 설정 문제입니다.

판단 순서

  • 오류가 난 실행 방식에서 sys.executable을 출력합니다.
  • 그 경로로 -m pip --version을 실행해 pip 위치를 확인합니다.
  • 두 경로가 다르면 IDE·예약 실행기의 인터프리터를 맞춥니다.
  • 경로가 같으면 venv에 설치했는지와 배포명·import명을 구분합니다.
  • 그래도 실패하면 sys.path와 패키지 자체의 설치 문서를 확인합니다.

이 순서대로 확인하면 패키지가 설치되지 않은 문제와 다른 Python에 설치한 문제를 나눠서 다음 조치를 정할 수 있습니다. 경로가 다르면 설치 명령을 반복하지 말고 실행 인터프리터를 먼저 통일합니다. 경로가 같은데도 실패하면 배포 이름과 import 이름, IDE·예약 실행기의 인터프리터 설정을 확인합니다.

다음에는 파이썬 상대경로와 현재 작업 폴더 확인법을 이어서 확인하거나, requirements.txt로 같은 실행 환경을 재현하는 방법을 정리해 두면 좋습니다. 다음에는 requirements.txt로 같은 실행 환경을 재현하거나 예약 실행에서 선택된 Python 경로를 로그로 남겨 보세요.

출처: Python 공식 Installing Python modules 문서, sys.executable 문서, venv 문서, importlib.metadata 문서

Leave a Comment