프로젝트 폴더에서 VSCode 파이썬 디버깅 설정이 안 될 때 — 한 번에 해결

새 프로젝트 폴더를 열고 파이썬 코드를 실행하려는데 F5 키를 눌러도 'launch.json이 없습니다'라는 알림만 뜨고 실행이 안 되는 상황이라면, 바로 VSCode 파이썬 디버깅 설정 문제를 겪고 있는 것입니다. 이 문제는 VSCode가 현재 폴더를 독립적인 작업 공간으로 인식하지 못하거나, 필수 확장 프로그램이 디버그 구성 파일을 초기화하지 못해 발생합니다. 특히 파이썬은 다른 언어에 비해 환경 변수와 인터프리터 경로에 민감하기 때문에, 단순히 코드만 작성해서는 원활한 디버깅을 수행할 수 없습니다. 이 글에서는 복잡한 이론 없이 launch.json을 자동으로 생성하는 방법부터 인터프리터 연결까지 VSCode 파이썬 디버깅 설정을 완벽하게 마무리하는 구체적인 절차를 다룹니다. 초보자도 흔히 겪는 '모듈을 찾을 수 없음' 오류나 '경로 인식 실패' 문제를 근본적으로 해결하고, 개발 효율을 극대화할 수 있는 환경을 구축해 보겠습니다.

VSCode 파이썬 디버깅 설정의 원리와 도구 비교

VSCode는 기본적으로 텍스트 에디터이며, 파이썬 디버깅을 위해서는 Microsoft 공식 Python 확장 프로그램이 필수입니다. 많은 사용자가 에디터를 단순히 실행기로 착각하지만, 실제로는 '디버그 어댑터 프로토콜(Debug Adapter Protocol)'을 통해 에디터와 언어의 디버거를 중계하는 설정이 필요합니다. 이 과정이 생략되면 아무리 코드를 작성해도 실행 버튼이 회색으로 비활성화되거나 오류가 발생합니다. 즉, VSCode는 그 자체로는 파이썬 코드를 한 줄씩 실행시키는 기능을 내장하고 있지 않으며, 확장 프로그램이 파이썬의 pdb 디버거와 소통할 수 있는 통로인 launch.json을 요구하는 것입니다.

실제 사용자들은 다른 언어와 비교할 때 파이썬 환경 설정의 까다로움을 종종 호소합니다. 예를 들어 Go 언어 사용자는 Clien.net에서 "구체적으로 go를 예로 들자면, go sdk, delve, vscode, go 익스텐션 설치하고 디렉토리에 main.go와 go.mod 생성 하신 다음에 vscode로 해당 디렉토리와 저 main.go를 열면 그냥 그대로 편집, 빌드, 디버깅 등이 다 되는 것....이"라고 말하며 설정의 자동화를 칭찬한 바 있습니다. 반면 파이썬은 사용자가 직접 인터프리터를 지정하고 경로를 확인해야 하는 경우가 빈번하여, 도구의 특성을 명확히 이해할 필요가 있습니다. 이는 파이썬이 가진 '동적 타이핑' 언어의 특성과 다양한 라이브러리 생태계가 복합적으로 작용하기 때문입니다.

또한, VSCode의 '작업 공간(Workspace)' 개념을 이해하는 것이 중요합니다. 단순히 폴더를 열 때와 '작업 공간으로 저장'할 때의 설정 파일 저장 위치가 다르기 때문입니다. .vscode 폴더는 프로젝트의 루트 디렉토리에 생성되어야 하며, 여기에 launch.json이 위치해야 VSCode가 현재 프로젝트에 맞는 디버깅 규칙을 찾을 수 있습니다. 만약 상위 폴더를 잘못 지정했다면, 아무리 F5를 눌러도 하위 폴더의 설정을 인식하지 못해 'launch.json이 없습니다'라는 오류가 반복됩니다. 따라서 디버깅 설정에 앞서 현재 내가 편집기에서 어떤 범위를 작업 공간으로 삼고 있는지 확인하는 과정이 선행되어야 합니다.

아래는 파이썬 개발 환경을 구축할 때 선택할 수 있는 도구들을 비교한 표입니다. 현재 VSCode 설정에 어려움을 겪고 있다면 대안을 고려해 보는 것도 좋습니다. 하지만 VSCode는 무료이면서도 확장성이 뛰어나므로, 설정 원리만 익히면 가장 강력한 도구가 될 수 있습니다.

Photo by Simon Petereit on Pexels

launch.json 자동 생성으로 즉시 실행하기

VSCode에서 가장 빠르고 오류 없이 디버깅 환경을 구축하는 방법은 자동 생성 기능을 활용하는 것입니다. 수동으로 파일을 만들어 JSON 형식을 맞추는 방법도 있지만, 오타나 경로 지정 오류로 인해 시간을 낭비할 수 있습니다. 자동 생성 기능은 현재 활성화된 파일과 확장 프로그램을 분석하여 최적의 기본 설정을 작성해 줍니다. 이 과정은 단순히 파일 하나를 만드는 것이 아니라, 현재 프로젝트의 구조를 VSCode 디버거에게 등록하는 중요한 의식입니다.

자동 생성을 진행하기 전에 반드시 확인해야 할 것은 '현재 편집기에 파이썬 파일이 열려 있고 활성화되어 있는가'입니다. VSCode는 어떤 파일을 기준으로 디버깅을 시작할지 알지 못하기 때문에, 디버깅하려는 메인 스크립트(예: main.py 또는 app.py)를 탭에서 선택한 상태여야 합니다. 만약 텍스트 파일이나 빈 문서만 떠 있으면 자동 생성 메뉴가 비활성화되거나 다른 언어의 설정이 생성될 수 있습니다.

[단계별 가이드] launch.json 7단계 자동 생성법

1. VSCode 좌측 사이드바에서 '실행 및 디버그' 아이콘(플레이 버튼과 벌레 모양)을 클릭합니다. 단축키 Ctrl+Shift+D를 사용해도 됩니다.
2. 화면 중앙 혹은 사이드바 상단에 "launch.json 파일을 만들어 debug.json을 구성합니다."라는 링크가 보입니다. 이를 클릭합니다.
3. 상단 드롭다운 메뉴에서 환경 검색창이 뜹니다. 여기서 "Python File"을 선택합니다. 이는 현재 열린 파일을 직접 실행하는 가장 일반적인 설정입니다.
4. VSCode가 자동으로 프로젝트 루트 경로에 .vscode 폴더를 생성하고 그 안에 launch.json 파일을 작성합니다.
5. 생성된 파일을 확인하면 "configurations": [...] 배열 안에 기본 설정이 들어있는 것을 볼 수 있습니다.
6. 이제 코드 왼쪽 라인 넘버 옆의 빈 공간을 클릭하여 빨간색 점(Breakpoint)을 하나 찍어봅니다.
7. F5 키를 누르거나 상단의 녹색 실행 버튼을 누릅니다. 더 이상 'launch.json 없음' 오류가 뜨지 않고, 중단점에서 프로그램이 멈추며 디버깅이 시작되는 것을 확인할 수 있습니다.

자동 생성 후에도 실행이 안 된다면, 생성된 launch.json의 "program" 속성값을 확인해야 합니다. 기본값은 "${file}"으로 되어 있어 현재 활성화된 파일을 실행합니다. 만약 특정 파일을 항상 실행시키고 싶다면 이 부분을 해당 파일 경로로 수정해야 합니다. 예를 들어, 프로젝트가 복잡하게 구성되어 있다면 "program": "${workspaceFolder}/src/main.py"와 같이 절대 경로 대신 워크스페이스 변수를 사용해 설정하는 것이 좋습니다.

파이썬 인터프리터 경로 및 가상 환경 연결

디버깅 설정 파일이 생성되었음에도 오류가 발생한다면, 그 다음 원인은 90% 이상 인터프리터(Interpreter) 문제입니다. VSCode는 시스템에 설치된 파이썬 여러 버전이나, 프로젝트별로 생성된 가상 환경(Virtual Environment) 중에서 어느 것을 사용해야 할지 자동으로 판단하지 못할 때가 많습니다. 특히 pip install로 설치한 외부 라이브러리를 찾을 수 없다는

• VSCode에서 제대로 Debugging 하는 방법 — chanmuzi
• [코딩유치원] VS CDOE 파이썬 디버깅(Debugging) 기초 다지기 :: 코딩유치원
• VSCode _ 디버깅하는 방법 (feat. Python - FastAPI)