VSCode 파이썬 디버깅 안될 때, 3가지 설정 점검

VSCode 파이썬 디버깅 설정 오류 해결, 중단점을 찍고 F5를 눌렀지만 콘솔에 아무런 반응이 없거나 'Launch configuration not found'라는 불투명한 메시지만 띄워주며 한숨 쉬고 있는 상황입니다. 이러한 문제는 대부분 VSCode가 사용하려는 파이썬 인터프리터와 실제 프로젝트 환경이 일치하지 않거나, 디버깅 구성 파일인 launch.json의 경로 설정이 꼬였기 때문에 발생합니다. 이 글에서는 VSCode 파이썬 디버깅 설정 오류 해결을 위해 반드시 확인해야 할 인터프리터 선택, launch.json 구성, 가상 환경 연결의 3가지 핵심 요소를 구체적인 명령어와 시나리오로 분석하여 해결책을 제시합니다.

함께 보면 좋은 글: 맥북 M4 성능 2026 최적화, 느려짐 방지

인터프리터 경로 불일치: 가장 흔한 원인 분석

VSCode가 파이썬 코드를 실행할 때 가장 기본적으로 참조하는 정보는 인터프리터의 경로입니다. 사용자가 pip install 명령어로 라이브러리를 설치한 가상 환경(virtual environment)과 VSCode가 참조하는 시스템 기본 파이썬이 다르면, 디버깅 시 ModuleNotFoundError가 발생하거나 중단점이 무시됩니다. 예를 들어, 프로젝트 폴더 내 venv 폴더에 requests 라이브러리를 설치했는데, VSCode가 /usr/bin/python3를 사용하도록 설정되어 있다면 디버거는 해당 모듈을 찾지 못해 즉시 종료됩니다. 이러한 경로 불일치 문제는 OS 업데이트나 새로운 파이썬 버전 설치 시 시스템 PATH가 변경되면서 발생하는 경우가 가장 많습니다.

특히 팀 프로젝트나 여러 프로젝트를 병행할 때, 전역 설치된 패키지와 로컬 프로젝트의 의존성이 섞이면 디버깅 결과를 신뢰할 수 없게 됩니다. '내 로컬에서는 잘 되는데 왜 안 되지?'라는 의문은 대부분 이 인터프리터 경로 오류에서 기인합니다. 따라서 프로젝트를 처음 열거나 디버깅 오류가 발생했을 때는 가상 환경 내의 파이썬 실행 파일이 VSCode에서 선택되었는지 확인하는 것이 선행되어야 합니다. 터미널에서 which python이나 where python 명령어로 현재 경로를 확인하고, 이것이 VSCode 하단 상태바에 표시된 경로와 일치하는지 비교하는 습관을 들이는 것이 좋습니다.

이 문제를 해결하기 위해서는 VSCode의 명령 팔레트를 통해 인터프리터를 명확하게 지정해야 합니다. 윈도우나 리눅스 사용자는 Ctrl+Shift+P, 맥 사용자는 Cmd+Shift+P를 눌러 'Python: Select Interpreter'를 입력하고 실행합니다. 목록에 가상 환경이 나타나지 않는다면 'Enter interpreter path...'를 선택하여 수동으로 ./venv/bin/python 또는 .\venv\Scripts\python.exe 경로를 지정해야 합니다. Python 공식 문서에서도 모듈 격리를 위해 프로젝트별 가상 환경 사용을 강력히 권장하며, 이는 디버깅 안정성의 필수 조건입니다.

Photo by Daniil Komov on Pexels

launch.json 파일 구성: 경로와 인자 설정 미스 해결

인터프리터가 올바르게 설정되었다면 다음으로 살펴볼 부분은 디버깅 구성 파일인 launch.json입니다. 이 파일은 .vscode 폴더 내에 위치하며, 디버거가 어떤 파일을 시작점으로 삼을지, 어떤 인자를 넘겨줄지를 정의합니다. 많은 사용자가 "program": "${file}" 설정을 그대로 두고, 하위 폴더에 있는 파일을 열고 디버깅을 시도하여 상대 경로 오류를 겪습니다. 특히 src 폴더 안의 main.py를 실행할 때, 작업 디렉터리가 루트가 아니라 src로 잡히면서 데이터 파일을 찾지 못하는 경우가 빈번합니다.

또한, launch.json에는 단순히 파일 경로뿐만 아니라 디버거의 동작 방식을 제어하는 다양한 옵션이 존재합니다. 예를 들어 "justMyCode": true(기본값)로 설정되어 있으면, 사용자가 작성한 코드에서만 중단점이 작동하고 외부 라이브러리 내부로는 스텝 인(Step Into) 할 수 없습니다. 라이브러리 내부 동작을 추적해야 하는 디버깅 상황이라면 이 옵션을 false로 변경해야 합니다. 또한, 환경 변수가 필요한 애플리케이션의 경우 "env" 속성을 통해 키-값 쌍을 전달하여 OS 레벨의 설정을 주입할 수 있습니다.

이를 해결하려면 launch.json을 열어 "program" 속성을 "${workspaceFolder}/main.py"와 같이 워크스페이스 루트 기준의 절대 경로 형태로 수정하는 것이 좋습니다. 또한, 외부 인자가 필요한 스크립트라면 "args" 배열에 값을 추가해야 합니다. VSCode 1.85 버전 이상에서는 디버그 버튼 옆의 'Add Configuration...' 기능을 통해 템플릿을 자동으로 생성할 수 있으므로, 수동 입력으로 인한 오타를 줄이는 데 활용하십시오. 특히 "cwd"(Current Working Directory) 설정은 상대 경로를 사용하는 파일 입출력 작업에서 필수적이므로, 프로젝트 루트를 가리키도록 명시적으로 설정하는 것이 오류를 방지하는 지름길입니다.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/src/main.py",
            "console": "integratedTerminal",
            "args": ["--mode", "dev"],
            "cwd": "${workspaceFolder}",
            "env": {
                "MY_API_KEY": "test_key_123"
            },
            "justMyCode": false
        }
    ]
}