VS Code에서 파이썬 모듈을 못 찾을 때는 실행 중인 인터프리터와 pip 설치 경로부터 확인하는 것이 빠릅니다. 설치 성공 메시지가 나왔는데도 ModuleNotFoundError: No module named 'requests'가 나타난다면, 패키지를 설치한 파이썬과 코드를 실행한 파이썬이 다른지 먼저 살펴봐야 합니다.
이 문제는 패키지 재설치만 반복하면 원인을 놓치기 쉽습니다. 환경의 의미를 이해한 뒤 실행 경로 확인, 인터프리터 선택, 새 터미널에서 설치 확인 순서로 진행하면 어느 지점에서 환경이 어긋났는지 구분할 수 있습니다.
📌 핵심 요약
- 오류가 발생한 실행 방식으로
sys.executable을 출력합니다. - 터미널에서는
python -m pip --version과python -m pip show 패키지명으로 설치 환경을 확인합니다. - 인터프리터를 바꾼 뒤에는 새 터미널을 열고 경로를 다시 대조합니다.
1. ModuleNotFoundError와 파이썬 가상환경의 관계 이해하기
파이썬 환경은 특정 인터프리터와 그 환경에서 사용할 패키지들을 묶어 구분하는 실행 단위입니다. 같은 컴퓨터에 시스템 Python, 프로젝트의 .venv, Conda 환경이 함께 있으면 각각 사용할 수 있는 패키지가 달라질 수 있습니다. 따라서 한 환경에 설치한 패키지가 다른 환경에서도 자동으로 사용되는 것은 아닙니다.
ModuleNotFoundError는 현재 실행 중인 파이썬이 요청한 모듈을 검색 경로에서 찾지 못했다는 뜻입니다. 패키지가 실제로 설치되지 않았을 수도 있지만, 다른 환경에 설치되어 있거나 모듈 이름·프로젝트 구조가 잘못된 경우도 있습니다. 오류 문구만 보고 파이썬 전체를 다시 설치할 필요는 없습니다.
예를 들어 터미널의 python은 시스템 Python을 가리키는데, VS Code의 Python 실행 명령은 프로젝트의 .venv를 사용하도록 설정될 수 있습니다. 이런 구성에서는 터미널의 설치 성공과 실행 버튼의 가져오기 실패가 동시에 발생해도 모순이 아닙니다. 아래 절차에서는 이 두 실행 경로를 직접 비교합니다.
1. ModuleNotFoundError와 파이썬 가상환경의 관계 … 실시간 확인하기
2. sys.executable로 VS Code 실행 버튼과 터미널 경로 확인하기
먼저 오류가 발생하는 파일에서 실패한 import 문보다 위에 다음 코드를 넣습니다. 그다음 평소 오류가 나던 실행 버튼이나 디버깅 방식으로 파일을 실행합니다. 별도의 방식으로 실행하면 문제를 일으킨 환경을 확인하지 못할 수 있습니다.
import sys
print("실행 인터프리터:", sys.executable)
import requestssys.executable은 현재 실행 중인 파이썬 인터프리터 실행 파일의 절대 경로를 제공합니다. 일반적인 Python 설치에서는 이 값으로 어떤 실행 파일을 사용했는지 확인할 수 있습니다. Python 공식 문서는 실행 파일 경로를 알아낼 수 없는 특수한 경우에는 빈 문자열이나 None이 될 수 있다고 설명합니다. [Python 공식 sys.executable 문서](https://docs.python.org/3/library/sys.html#sys.executable)
이어서 VS Code 통합 터미널에서도 다음 명령을 실행합니다. 코드 실행 결과와 터미널 결과의 경로가 같은지 비교하는 단계입니다.
python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip show requestspython -m pip --version은 pip 버전과 pip 모듈이 위치한 경로 등을 보여 줍니다. 반면 python -m pip show requests의 Location은 requests 패키지의 설치 위치를 확인하는 데 사용합니다. pip 자체의 위치와 대상 패키지의 위치는 서로 다른 확인 항목입니다. [PyPA pip show 공식 문서](https://pip.pypa.io/en/stable/cli/pip_show/)
| 확인 항목 | 판단할 내용 |
|---|---|
| 파일에서 출력한 sys.executable | 오류가 발생한 실제 실행 인터프리터 |
| 터미널에서 출력한 sys.executable | 터미널의 python 명령이 사용하는 실행 파일 |
| python -m pip --version | 해당 python으로 실행되는 pip의 버전과 위치 |
| pip show의 Location | 대상 패키지의 설치 위치 |
인터프리터 경로와 패키지 경로가 문자 그대로 같아야 하는 것은 아닙니다. Windows 가상환경에서는 실행 파일이 .venv\Scripts\python.exe에 있고 패키지는 .venv\Lib\site-packages에 있을 수 있습니다. 두 경로가 의도한 같은 환경에 속하는지를 판단해야 합니다.
2. sys.executable로 VS Code 실행 버튼과 터미널… 바로가기
3. Python: Select Interpreter로 프로젝트 환경 맞추기
경로가 다르면 먼저 프로젝트에서 사용할 환경을 정합니다. 이미 프로젝트용 가상환경이 있다면 그 환경을 선택하고, 팀에서 지정한 실행 환경이 있다면 해당 경로를 기준으로 맞춥니다. 패키지가 설치되어 있다는 이유만으로 무관한 전역 환경을 선택하면 프로젝트 의존성이 뒤섞일 수 있습니다.
- 파이썬 파일을 연 상태에서 VS Code 하단 상태 표시줄의 Python 버전을 선택합니다.
- 또는 명령 팔레트를 열어
Python: Select Interpreter를 실행합니다. - 환경 이름과 함께 표시되는 실행 파일 경로를 확인하고 프로젝트 환경을 선택합니다.
- 파일을 다시 실행해
sys.executable이 의도한 경로로 바뀌었는지 확인합니다.
Microsoft 공식 문서에 따르면 선택한 환경은 Python 실행, 디버깅, IntelliSense에 사용됩니다. 2026년 기준 환경 관리 문서에서는 Python Environments 확장의 환경 검색·활성화 설정도 함께 안내합니다. 다만 별도 실행 확장의 버튼을 사용하는 경우에는 그 확장의 실행 설정을 확인해야 하므로, 버튼 모양보다 실제 출력 경로를 기준으로 판단하는 편이 정확합니다.
가상환경이 목록에 나타나지 않으면 Python Environments: Refresh All Environment Managers를 실행합니다. 기본 작업 공간 검색 패턴은 ./**/.venv이며, 다른 이름이나 위치의 환경은 검색 경로 설정을 추가해야 할 수 있습니다. 이 검색·선택 동작은 Microsoft의 현재 문서에서 확인할 수 있습니다. [Microsoft VS Code 환경 관리 문서](https://code.visualstudio.com/docs/python/environments)
3. Python: Select Interpreter로 프로젝트 환… 신청하기
4. 새 터미널에서 python -m pip로 정확한 환경에 설치하기
인터프리터를 바꾼 뒤에도 이전 터미널의 환경이 그대로 남아 있을 수 있습니다. 상태 표시줄의 선택과 이미 실행 중인 셸의 상태는 별도로 확인해야 합니다. 실행 중인 작업을 마친 뒤 기존 터미널을 종료하고 새 터미널을 열어 경로를 다시 출력하면 혼동을 줄일 수 있습니다.
Python Environments 확장의 현재 문서상 python-envs.terminal.autoActivationType 기본값은 command입니다. 새 터미널이 열리면 활성화 명령을 실행하는 방식이며, off로 설정하면 자동 활성화하지 않습니다. 설정을 변경한 경우에도 터미널을 다시 시작해야 적용됩니다.
python -c "import sys; print(sys.executable)"
python -m pip --version
python -m pip show requests새 터미널의 실행 경로가 올바른데 패키지를 찾을 수 없다고 나오면 그때 설치합니다. python -m pip는 앞에 지정한 python으로 pip를 실행하므로, 단독 pip 명령보다 설치 대상을 분명하게 표현할 수 있습니다. 프로젝트에 의존성 관리 파일이나 전용 설치 절차가 있다면 해당 절차를 우선합니다.
python -m pip install requests
python -m pip show requests
python -c "import requests; print(requests.__file__)"활성화 상태가 불확실하면 실행 파일을 직접 지정하는 방법도 있습니다. 다음은 프로젝트 루트에 .venv가 있는 경우의 예시이며, 실제 환경 위치에 맞춰 사용합니다. Windows PowerShell에서는 따옴표로 감싼 실행 경로 앞에 호출 연산자 &를 붙입니다.
# Windows PowerShell
& ".\.venv\Scripts\python.exe" -m pip install requests
# macOS / Linux
./.venv/bin/python -m pip install requests진단 관점에서 중요한 것은 설치 명령의 성공 여부보다 그 명령을 실행한 인터프리터의 정체입니다. 명시적인 실행 경로를 사용하면 셸의 활성화 상태라는 변수를 줄일 수 있습니다. 환경 불일치가 확인된 상황에서는 무조건 재설치하는 것보다 설치 대상을 먼저 고정하는 편이 원인과 해결을 연결하기 쉽습니다.
4. 새 터미널에서 python -m pip로 정확한 환경에 설치하기
5. 경로를 맞춰도 모듈 오류가 남을 때 확인할 설정
터미널에서는 성공하지만 디버깅에서만 실패한다면 .vscode/launch.json을 살펴봅니다. 디버거는 기본적으로 선택한 환경을 사용하지만, 구성의 python 속성에 다른 실행 파일이 지정되어 있으면 그 설정으로 실행할 수 있습니다. 디버깅 중 출력한 sys.executable을 기준으로 오래된 경로가 남아 있는지 판단합니다.
노트북 파일에서는 셀 안에서 같은 경로 확인 코드를 실행하고 커널도 확인해야 합니다. 일반 파이썬 파일에서 선택한 환경과 노트북의 실행 커널을 같은 것으로 단정하면 원인이 다시 숨을 수 있습니다. VS Code 공식 문서도 Jupyter 노트북의 환경 검색이 Python Environments와 다른 API를 사용한다고 설명합니다.
실행 경로가 일치한다면 오류 메시지의 모듈 이름과 전체 traceback을 다시 읽습니다. 직접 가져온 패키지가 아니라 그 패키지 내부에서 필요한 다른 의존성을 못 찾았을 수도 있습니다. 설치할 때 쓰는 배포 패키지 이름과 코드의 import 이름이 다른 경우에는 해당 패키지 공식 설치 문서로 이름을 확인합니다.
프로젝트 내부 모듈에서 발생한 오류라면 실행 위치와 폴더 구조도 점검합니다. 다음 명령은 현재 작업 폴더와 파이썬의 모듈 검색 경로를 보여 줍니다. 외부 패키지 설치 문제인지, 프로젝트 코드를 찾는 경로 문제인지 구분한 뒤 수정해야 합니다.
python -c "import os, sys; print(os.getcwd()); print(*sys.path, sep='\n')"마지막 확인은 처음 실패했던 실행 방식으로 진행합니다. 터미널에서만 가져오기에 성공했다고 끝내면 실행 버튼이나 디버거의 설정 차이가 남을 수 있습니다. 반대로 실제 코드는 실행되는데 편집기에만 가져오기 경고가 남는다면 런타임 오류와 언어 분석 경고를 나누어 살펴보는 것이 좋습니다.
- 오류가 발생한 실행 방식의
sys.executable을 확인했는가? - 새 터미널의
python이 의도한 환경을 가리키는가? - 같은 인터프리터로 실행한 pip에서 패키지 설치 위치를 확인했는가?
- 처음 실패했던 파일 실행 또는 디버깅으로 가져오기에 성공했는가?
VS Code의 파이썬 모듈 오류를 해결하는 기준은 단순합니다. 코드를 실행하는 파이썬과 패키지를 설치하는 파이썬을 맞추고, 원래의 실행 방식으로 결과를 검증하는 것입니다. 경로가 일치한 뒤에도 실패할 때 모듈 이름, 의존성, 프로젝트 검색 경로를 살펴보면 불필요한 재설치를 줄일 수 있습니다.