pip 설치는 성공했는데 실행할 때 ModuleNotFoundError가 난다면, 먼저 패키지를 다시 설치하기보다 설치에 사용한 Python과 실행에 사용한 Python이 같은지 확인해야 합니다. 이 오류는 Python이 import할 모듈을 찾지 못했다는 뜻이며, pip가 성공했다는 사실만으로 현재 실행 환경에 설치되었다고 단정할 수는 없습니다.
먼저 오류의 범위를 좁히기
ModuleNotFoundError는 import 대상 모듈을 찾지 못할 때 발생합니다. Python은 모듈 검색 경로를 사용하므로, 오류가 보이면 설치 명령이 어느 Python을 사용했는지, 실제 프로그램은 어느 Python으로 실행되는지, 설치한 배포 패키지 이름과 코드의 import 이름이 같은지를 나누어 확인해야 합니다. Python 공식 import 문서는 import가 검색 경로를 통해 대상을 찾는 구조임을 설명합니다.
1. pip와 Python의 경로를 나란히 확인하기
터미널에서 다음을 실행합니다.
python -m pip -V
python -c "import sys; print(sys.executable); print(*sys.path, sep='\\n')"
python -m pip는 지정한 python 인터프리터를 통해 pip를 실행합니다. sys.executable은 현재 Python 실행 파일의 절대 경로이고, sys.path는 모듈 검색에 사용하는 경로 목록입니다. 두 값은 Python sys 공식 문서의 설명에 해당합니다.
Windows에서 여러 Python이 설치된 경우에는 py -m pip -V와 py -c "import sys; print(sys.executable)"처럼 실행할 Python을 명시할 수도 있습니다. 핵심은 pip의 환경과 프로그램 실행 시 확인한 sys.executable이 의도한 환경인지 비교하는 것입니다.
2. 같은 인터프리터로 설치하기
경로가 다르면 pip install만 다시 입력하지 말고 프로그램을 실행할 Python으로 설치합니다.
python -m pip install 패키지이름
프로젝트에서 가상환경을 쓴다면 먼저 활성화합니다.
python -m venv .venv
## macOS/Linux
source .venv/bin/activate
## Windows PowerShell
.venv\\Scripts\\Activate.ps1
python -m pip install 패키지이름
Python Packaging User Guide는 python -m venv로 프로젝트별 가상환경을 만들고, 활성화하면 해당 환경의 Python과 pip가 PATH에서 우선 사용된다고 안내합니다. 기준은 pip와 가상환경 공식 가이드에서 확인할 수 있습니다.
기존 환경이 의도한 경로이고 다른 패키지도 정상이라면 필요한 패키지만 그 환경에 설치하면 됩니다. 프로젝트가 어떤 환경을 사용해야 하는지 불명확하다면 .venv를 선택하고 실행 경로를 다시 맞추는 판단이 더 안전할 수 있습니다.
3. VS Code의 실행 인터프리터 확인하기
VS Code의 실행·디버깅 환경이 터미널과 다르면 같은 오류가 날 수 있습니다. 명령 팔레트의 Python: Select Interpreter를 열고 프로젝트가 사용할 가상환경 또는 Python을 선택합니다. 선택한 환경은 코드 실행·디버깅·언어 기능에 사용됩니다. 이 동작은 VS Code Python 환경 공식 문서에 설명되어 있습니다.
선택 뒤 VS Code 터미널에서 python -c "import sys; print(sys.executable)"와 python -m pip -V를 다시 실행해 프로젝트에서 의도한 환경을 가리키는지 확인합니다. 그 다음 같은 터미널에서 프로그램을 실행합니다.
4. 패키지 이름과 import 이름을 구분하기
설치 명령에 쓴 배포 패키지 이름과 코드에서 쓰는 import 이름은 다를 수 있습니다. 이름이 다르다는 이유만으로 설치가 실패했다고 결론 내리지 말고 해당 패키지의 공식 문서에서 import 예제를 확인해야 합니다. 이 차이는 Python Packaging User Guide가 설명하는 Distribution Package와 Import Package의 구분에 해당합니다.
5. 재설치 전에 판단할 기준
| 확인 결과 | 다음 행동 |
|---|---|
python -m pip -V와 실행 Python이 서로 다름 |
실행할 Python으로 python -m pip install 실행 |
| 가상환경이 의도와 다름 | 올바른 가상환경을 활성화하고 VS Code 인터프리터도 선택 |
| 경로는 같지만 import 이름이 의심됨 | 패키지 공식 문서의 import 이름 확인 |
| 경로와 이름이 모두 맞는데 계속 실패함 | sys.path, 오탈자, 패키지별 공식 설치·호환성 문서 추가 확인 |
마지막 경우에는 패키지별 빌드나 호환성 문제일 수 있습니다. 확인하지 않은 원인을 Python 전체의 문제로 확대하지 않는 것이 운영상 중요합니다.
정리: 재설치보다 실행 환경의 일치부터
pip 설치 후 ModuleNotFoundError가 나면 python -m pip -V와 sys.executable로 설치와 실행의 기준점을 먼저 맞추고, 가상환경과 VS Code 인터프리터를 같은 환경으로 선택합니다. 그 다음에도 문제가 남을 때 패키지 이름과 import 이름, sys.path, 패키지 공식 문서를 순서대로 확인하면 됩니다.
다음으로는 python -m pip와 pip가 실제로 어떤 차이를 만드는지, 또는 프로젝트에서 가상환경을 새로 만들지 기존 환경을 고칠지 판단하는 기준을 이어서 살펴볼 수 있습니다.
참고 자료
- Python import system — Python Software Foundation
- sys — System-specific parameters and functions — Python Software Foundation
- Install packages in a virtual environment using pip and venv — Python Packaging Authority
- Python environments in VS Code — Microsoft