No module named 오류는 패키지 설치 여부보다 Python 실행 환경과 pip 설치 환경이 같은지 확인하는 것이 핵심입니다.
Python에서 ModuleNotFoundError: No module named 오류가 나면 먼저 “패키지를 설치했는가”보다 “지금 실행하는 Python과 pip가 같은 환경을 보고 있는가”를 확인해야 합니다. 특히 venv를 만들었지만 활성화하지 않았거나, VSCode가 다른 인터프리터를 선택하고 있으면 설치한 패키지를 Python이 찾지 못할 수 있습니다.
대표적인 오류 메시지는 아래처럼 표시됩니다.
ModuleNotFoundError: No module named 'requests'📑목차[보기]
오류 메시지 원문
ModuleNotFoundError는 Python이 import하려는 모듈을 현재 실행 환경에서 찾지 못할 때 나오는 오류입니다. 패키지명이 다를 수도 있지만, 초보자에게 가장 흔한 원인은 “설치한 Python 환경”과 “실행한 Python 환경”이 다른 경우입니다.
Traceback (most recent call last):
File "main.py", line 1, in <module>
import requests
ModuleNotFoundError: No module named 'requests'예를 들어 터미널에서는 pip install requests를 실행했는데, VSCode의 실행 버튼은 다른 Python 인터프리터로 파일을 실행하면 위 오류가 계속 날 수 있습니다.
언제 발생하는 오류인지
이 오류는 Python 파일을 실행하는 순간 import 문에서 자주 발생합니다. 패키지를 설치하지 않았을 때도 생기지만, 이미 설치했는데도 계속 뜬다면 환경 경로를 먼저 의심해야 합니다.
| 상황 | 자주 생기는 원인 | 먼저 볼 것 |
|---|---|---|
| pip install 후 import 실패 | pip와 python 경로가 다름 | python -m pip show |
| VSCode Run 버튼 실행 실패 | 다른 인터프리터 선택 | Python: Select Interpreter |
| venv 생성 후 import 실패 | venv 미활성화 또는 다른 venv 사용 | 터미널 앞 환경명 |
| 프로젝트를 다른 PC로 옮긴 뒤 실패 | 의존성 미설치 | requirements.txt |
원인 3가지
1. Python 실행 경로와 pip 설치 경로가 다릅니다
가장 흔한 원인은 python으로 실행하는 환경과 pip가 패키지를 설치하는 환경이 다른 경우입니다. PC에 Python이 여러 개 설치되어 있거나, venv와 전역 Python이 함께 있으면 이런 상황이 자주 생깁니다.
python --version
python -m pip --version
python -m pip show requestspython -m pip 형식은 “지금 실행할 Python에 연결된 pip”를 쓰는 방식이라 설치 위치를 확인하기 쉽습니다.
2. VSCode 인터프리터가 다른 환경을 보고 있습니다
터미널에서는 venv가 활성화되어 있어도 VSCode 오른쪽 위 실행 버튼이나 디버그 설정은 다른 인터프리터를 사용할 수 있습니다. 이 경우 터미널에서 패키지가 보여도 Run 버튼으로 실행하면 No module named 오류가 납니다.
VSCode에서는 명령 팔레트에서 Python: Select Interpreter를 실행하고, 프로젝트의 .venv, venv, conda 환경 중 실제로 패키지를 설치한 환경을 선택해야 합니다.
3. venv 또는 conda 환경이 활성화되지 않았습니다
가상환경은 프로젝트마다 패키지를 분리하기 위한 공간입니다. venv 안에 설치한 패키지는 venv를 활성화한 Python에서만 바로 사용할 수 있습니다. 반대로 전역 Python에 설치한 패키지는 프로젝트 venv 안에서 보이지 않을 수 있습니다.
핵심 기준
ModuleNotFoundError는 “설치했는데도 없다”가 아니라 “현재 실행 중인 Python 환경에는 없다”로 이해하면 해결이 빨라집니다. 실행 경로와 설치 경로를 먼저 맞춘 뒤 패키지명을 확인하세요.
빠른 해결 방법
처음에는 삭제나 초기화보다 현재 환경을 확인하는 명령부터 실행하는 것이 안전합니다. 아래 순서대로 보면 Python 경로, pip 경로, 설치 여부를 빠르게 좁힐 수 있습니다.
1. 현재 Python 경로를 확인합니다
먼저 터미널에서 지금 실행되는 Python이 어디에 있는지 확인합니다.
python --version
python -c "import sys; print(sys.executable)"Mac이나 Linux에서는 환경에 따라 python3를 써야 할 수 있습니다.
python3 --version
python3 -c "import sys; print(sys.executable)"2. pip가 어느 Python에 연결됐는지 확인합니다
다음으로 pip가 어느 Python 환경에 설치하는지 확인합니다. 단순히 pip --version만 보는 것보다 python -m pip --version을 함께 보는 것이 좋습니다.
python -m pip --version
python -m pip show requestspip show 결과가 나오지 않으면 현재 Python 환경에는 해당 패키지가 없다는 뜻입니다.
3. 현재 Python에 연결된 pip로 다시 설치합니다
설치가 필요한 경우에는 아래처럼 python -m pip install 형식을 사용합니다. 패키지명은 실제로 import하려는 패키지에 맞게 바꿉니다.
python -m pip install requestsMac이나 Linux에서 python3를 쓰는 환경이라면 아래처럼 실행합니다.
python3 -m pip install requestsWindows·Mac·Linux 차이
운영체제에 따라 Python 실행 명령과 경로 확인 명령이 조금씩 다릅니다. 같은 명령을 그대로 따라 했는데 안 된다면 운영체제별 명령 차이를 먼저 확인하세요.
| 환경 | 확인 명령 | 주의할 점 |
|---|---|---|
| Windows | where python |
py, python 명령이 다른 버전을 가리킬 수 있음 |
| Mac | which python3 |
python 대신 python3를 써야 하는 경우가 많음 |
| Linux | which python3 |
시스템 Python과 프로젝트 venv를 구분해야 함 |
Windows에서 py, python, pip가 헷갈릴 때
Windows에는 Python Launcher인 py가 함께 쓰이는 경우가 있습니다. python과 py가 같은 버전을 실행하는지 확인한 뒤, 패키지 설치도 같은 실행 명령에 맞추는 것이 좋습니다.
py --version
py -m pip --version
py -m pip show requestsMac과 Linux에서 python3, pip3가 헷갈릴 때
Mac과 Linux에서는 python 명령이 없거나 다른 버전을 가리킬 수 있습니다. 이때는 python3 -m pip로 실행하면 현재 Python 3에 연결된 pip를 확인하기 쉽습니다.
python3 --version
python3 -m pip --version
python3 -m pip show requestsVSCode에서 확인할 것
VSCode에서만 오류가 난다면 Python 코드보다 VSCode의 인터프리터 선택을 먼저 봐야 합니다. 터미널에서 실행할 때와 VSCode Run 버튼으로 실행할 때 다른 환경을 사용할 수 있기 때문입니다.
- VSCode에서 작업 폴더를 정확히 열었는지 확인합니다.
Ctrl + Shift + P또는Cmd + Shift + P를 누릅니다.Python: Select Interpreter를 검색합니다.- 프로젝트에서 사용하는
.venv,venv, conda 환경을 선택합니다. - VSCode 터미널을 새로 열어 환경명이 표시되는지 확인합니다.
- 터미널에서
python -c "import sys; print(sys.executable)"을 실행합니다. - 같은 터미널에서
python -m pip show 패키지명을 확인합니다.
VSCode에서 Python 인터프리터가 계속 다르게 잡힌다면 venv, conda, uv 환경을 따로 구분해 확인해야 합니다.
재발 방지 설정
ModuleNotFoundError를 줄이려면 프로젝트마다 가상환경을 만들고, 설치 명령과 실행 명령을 같은 환경으로 맞추는 습관이 중요합니다. 특히 여러 프로젝트를 오가거나 VSCode를 자주 쓰는 경우에는 인터프리터 선택을 프로젝트 단위로 고정하는 것이 좋습니다.
프로젝트마다 venv를 사용합니다
전역 Python에 모든 패키지를 설치하면 프로젝트가 늘어날수록 충돌을 찾기 어려워집니다. 새 프로젝트를 시작할 때는 가상환경을 만들고, 해당 환경을 VSCode 인터프리터로 선택하는 흐름을 기본으로 잡아두세요.
requirements.txt로 의존성을 남깁니다
혼자 쓰는 프로젝트라도 필요한 패키지를 requirements.txt로 관리하면 다른 PC나 새 환경에서 빠르게 복구할 수 있습니다. 다만 설치 오류가 날 때는 Python 버전과 패키지 버전 조건도 함께 확인해야 합니다.
python -m pip install 형식을 사용합니다
pip install만 입력하면 어떤 Python에 설치되는지 헷갈릴 수 있습니다. python -m pip install 형식을 쓰면 현재 실행할 Python과 연결된 pip를 사용하므로 경로 혼동을 줄일 수 있습니다.
주의할 점
오류가 난다고 바로 환경을 지우거나 다시 만들 필요는 없습니다. 먼저 현재 Python 경로, pip 경로, VSCode 인터프리터, 패키지 설치 여부를 확인한 뒤 필요한 패키지만 현재 환경에 맞춰 설치하는 순서가 안전합니다.
관련 명령어 정리
아래 명령어는 환경을 확인하는 용도입니다. 패키지 설치 위치와 실행 환경이 같은지 확인한 뒤, 필요한 경우에만 설치 명령을 실행하세요.
| 목적 | 명령어 | 확인할 내용 |
|---|---|---|
| Python 버전 확인 | python --version |
현재 Python 버전 |
| Python 경로 확인 | python -c "import sys; print(sys.executable)" |
실행 중인 Python 위치 |
| pip 연결 확인 | python -m pip --version |
pip가 연결된 Python 위치 |
| 패키지 설치 확인 | python -m pip show 패키지명 |
현재 환경에 설치됐는지 |
| 현재 환경에 설치 | python -m pip install 패키지명 |
현재 Python 환경에 설치 |
python --version
python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip show requests
python -m pip install requests공식 자료로 더 확인하기
Python 패키지 오류는 운영체제, 가상환경, pip, VSCode 설정이 함께 영향을 줍니다. 명령어가 조금씩 다르게 동작할 수 있으므로 공식 문서에서 venv, pip, VSCode 인터프리터 선택 흐름을 함께 확인하는 것이 좋습니다.
venv가 패키지를 독립된 환경에 설치하고 관리하는 방식과 기본 사용 흐름을 확인할 수 있습니다.
Python Virtual Environments and Packages 문서 확인하기VSCode에서 Python 인터프리터를 선택하고 프로젝트별 환경을 관리하는 방법을 확인할 수 있습니다.
VS Code Python environments 문서 확인하기함께 보면 좋은 글
자주 묻는 질문
Python ModuleNotFoundError는 패키지명보다 현재 실행 중인 Python, pip 설치 위치, VSCode 인터프리터가 같은 환경을 가리키는지부터 확인해야 빠르게 해결할 수 있습니다.
댓글