VSCode 파이썬 인터프리터 인식 오류 해결 완벽 가이드

VSCode에서 파이썬 코드를 실행했는데 ModuleNotFoundError가 뜨거나, 파일 경로를 찾지 못하는 오류를 겪고 있다면 이 글이 필요합니다. 대부분의 원인은 인터프리터 설정 오류 또는 작업 디렉터리(cwd) 불일치입니다. 이 문서에서는 VSCode 파이썬 환경 설정의 핵심 이슈와 해결 방법을 실무 관점에서 정리합니다.

VSCode파이썬인터프리터인식오류해결완벽가이드

1. 실행 경로 문제: launch.json으로 cwd 고정하기

VSCode는 기본적으로 워크스페이스 최상위 폴더를 작업 디렉터리(cwd)로 설정합니다. 이로 인해 os.getcwd()가 실제 파일 위치가 아닌 /home/eddy/Desktop 같은 상위 경로를 반환하며, 상대 경로 기반의 파일 입출력이 실패합니다.

해결 방법

Run and Debug 패널 열기 (Ctrl+Shift+D)
create a launch.json file 클릭
Debug Configuration에서 Python File 선택
생성된 .vscode/launch.json 파일에 아래 설정 추가:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "cwd": "${fileDirname}",  // 이 줄 추가 (위 줄 끝 콤마 필수)
      "console": "integratedTerminal"
    }
  ]
}

핵심: ${fileDirname}은 현재 실행 중인 파일의 디렉터리를 의미합니다. 이 설정 후에는 os.getcwd()가 파일 위치를 정확히 반환하며, 상대 경로 기반 파일 접근이 정상 작동합니다.

주의사항: JSON 문법상 마지막 항목을 제외한 모든 줄 끝에는 쉼표(,)가 필요합니다. 이를 누락하면 VSCode가 launch.json을 인식하지 못합니다.

2. 인터프리터 설정: 올바른 Python 경로 지정

VSCode가 파이썬을 인식하지 못하거나, 설치한 패키지를 찾지 못하는 경우 인터프리터 경로가 잘못 설정되었을 가능성이 높습니다.

인터프리터 선택 방법

F1 → Python: Select Interpreter 입력
또는 우측 하단 상태바의 Python 버전 표시 영역 클릭
목록에 원하는 버전이 없다면 Enter interpreter path... 선택 후 직접 경로 입력

설치된 파이썬 경로 확인 (코드)

import sys
print(sys.executable)
# 출력 예시: 'C:\\Users\\사용자명\\AppData\\Local\\Programs\\Python\\Python312\\python.exe'

Windows 환경변수 등록 (전역 사용)

시스템 환경변수 Path에 아래 두 경로를 추가하면 터미널 어디서든 python 명령어를 사용할 수 있습니다:

C:\Users\사용자명\AppData\Local\Programs\Python\Python312\
C:\Users\사용자명\AppData\Local\Programs\Python\Python312\Scripts\

실무 팁: 여러 버전의 Python이 설치된 경우, 환경변수 Path의 상단에 위치한 경로가 우선 적용됩니다. 순서 조정으로 기본 버전을 변경할 수 있습니다.

3. 모듈 경로 추가: sys.path와 extraPaths 설정

프로젝트 내 커스텀 모듈이나 서브 디렉터리의 패키지를 import할 때 ModuleNotFoundError가 발생한다면, Python이 해당 경로를 탐색하지 못하고 있는 것입니다.

일시적 경로 추가 (코드 레벨)

import sys, os
sys.path.append(os.path.dirname(os.getcwd()))  # 상위 디렉터리 추가

또는 환경변수 방식:

import os
os.environ["PYTHONPATH"] = "/path/to/your/module"

VSCode 전역 경로 설정 (.vscode/settings.json)

프로젝트 루트의 .vscode/settings.json에 아래 설정을 추가하면, Pylance 언어 서버가 해당 경로를 인식하여 자동완성과 타입 체크가 정상 작동합니다:

{
  "python.analysis.extraPaths": [
    "./jax",
    "./custom_modules"
  ]
}

모듈 탐색 우선순위: Python은 sys.modules → built-in modules → sys.path(현재 디렉터리, PYTHONPATH, site-packages) 순으로 모듈을 탐색합니다. 가상환경 활성화 시 venv의 site-packages가 우선 적용됩니다.

4. 가상환경(venv) 생성 및 VSCode 연결

프로젝트별로 독립된 패키지 환경을 구성하려면 가상환경(venv) 사용이 필수입니다. 특히 Docker 컨테이너와 로컬 환경을 병행하는 경우 의존성 충돌 방지를 위해 반드시 분리해야 합니다.

가상환경 생성 (Windows PowerShell 기준)

python -m venv env_test

VSCode에서 가상환경 인식시키기

중요: venv 폴더 자체를 열지 말고, venv를 포함한 상위 디렉터리(워크스페이스)를 열어야 VSCode가 자동 감지합니다.
F1 → Python: Select Interpreter
.\env_test\Scripts\python.exe 경로 선택
터미널에서 가상환경 활성화 확인 (프롬프트 앞에 (env_test) 표시)

패키지 설치 및 실행

pip install requests pandas
python your_script.py

PowerShell 실행 정책 오류 해결

가상환경 활성화 시 "이 시스템에서 스크립트를 실행할 수 없습니다" 오류가 발생하면:

Set-ExecutionPolicy Unrestricted -Scope CurrentUser

보안 권장사항: 개발 완료 후에는 Set-ExecutionPolicy Restricted로 원복하는 것을 권장합니다.

5. 디버거 설정: 브레이크포인트 이슈 해결

디버깅 중 브레이크포인트가 작동하지 않거나, 외부 라이브러리 내부를 추적해야 하는 경우 launch.json에 아래 옵션을 추가합니다:

{
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "cwd": "${fileDirname}",
      "justMyCode": false  // 외부 라이브러리 디버깅 허용
    }
  ]
}

실무 활용: justMyCode: false 설정 시 NumPy, Pandas 같은 외부 라이브러리 내부 동작을 Step Into로 추적할 수 있어, 복잡한 버그 원인 분석에 유용합니다.

요약 및 Action Item

핵심 정리:

launch.json에 "cwd": "${fileDirname}" 추가로 실행 경로 문제 해결
F1 → Select Interpreter로 올바른 Python 경로 지정 (가상환경 사용 시 venv의 python.exe 선택)
모듈 인식 오류는 python.analysis.extraPaths 또는 sys.path.append로 해결

지금 바로 실행할 것: 현재 프로젝트 루트에 .vscode 폴더를 생성하고, launch.json과 settings.json을 위 예시대로 작성하십시오. 이후 F5로 디버깅 실행 시 경로 오류가 사라지는 것을 확인할 수 있습니다.

#함께 읽으면 좋은 글

VS Code 필수 확장 프로그램 TOP 5 Python Web 개발자 생산성 3배 높이는 설정법 : 바로보기

Phantom-Shell

이 블로그 검색

Crontab 파이썬 스크립트 실행 안될 때 환경변수 PATH 문제 해결 완벽 정리