VSCode 파이썬 디버깅 설정—브레이크포인트 안 잡히면 해결법 정리

VSCode 파이썬 디버깅 설정을 마치고 빨간 점을 찍어 실행했는데, 코드가 멈추지 않고 그냥 끝까지 실행되어 버리는 상황에 직면해 답답함을 느껴보셨을 것입니다. 개발 과정에서 디버거는 단순한 실행 도구를 넘어, 변수의 상태를 실시간으로 확인하고 논리적 오류를 찾아내는 렌즈와 같습니다. 이런 현상은 대개 선택된 인터프리터와 설치된 확장 프로그램이 불일치하거나, 디버그 구성 파일인 launch.json이 프로젝트 상황에 맞게 생성되지 않아 발생합니다. 때로는 VSCode의 캐시가 꼬이거나, 가상 환경의 경로가 제대로 잡히지 않아 디버거 프로세스가 코드 내부로 진입하지 못하는 경우도 허다합니다. 이 글에서는 VSCode 파이썬 디버깅 설정의 모든 과정을 점검하고, 브레이크포인트가 무시되는 문제를 근본적으로 해결하는 방법을 구체적인 명령어와 예시로 정리합니다. 단순한 해결법을 넘어, 왜 문제가 발생하는지에 대한 원인 분석을 포함하여, 다양한 프로젝트 환경에서도 안정적으로 디버깅을 수행할 수 있는 완벽 가이드를 제공합니다.

함께 보면 좋은 글: CI/CD 파이프라인 안 될 때 — GitHub Act

VSCode 파이썬 확장 프로그램 설치 및 버전 확인

디버깅 기능이 작동하려면 가장 먼저 Microsoft에서 공식적으로 제공하는 파이썬 확장 프로그램이 설치되어 있어야 합니다. 일부 사용자는 Python 확장 대신 단순 코드 실행만 가능한 타사 플러그인이나, 문법 하이라이팅만 제공하는 가벼운 도구를 사용하기도 하는데, 이는 VSCode의 내부 디버거 어댑터(Debug Adapter Protocol)와 호환되지 않아 브레이크포인트가 작동하지 않는 주된 원인이 됩니다. 확장 프로그램 탭에서 Python을 검색할 때는 반드시 게시자(Publisher)가 'Microsoft'인지 확인하고, 현재 최신 버전인 2024.x.x 시리즈가 설치되어 있는지 점검해야 합니다. 구버전 확장 프로그램은 최신 파이썬 문법이나 타입 힌트를 제대로 해석하지 못해 디버깅 도중 변수 창이 비어 보이는 현상을 유발할 수도 있습니다.

확장 프로그램이 설치되어 있음에도 디버깅 버튼이 비활성화되거나 아이콘이 회색으로 표시된다면, 이는 VSCode 자체의 캐시 문제이거나 확장 프로그램이 충돌을 일으킨 경우입니다. 이때는 단순히 VSCode를 끄고 켜는 것보다 창을 다시 불러오는 기능을 통해 확장 프로그램 호스트를 재시작하는 것이 효과적입니다. 특히 맥 사용자의 경우 Cmd+Shift+P를 누르고, 윈도우 사용자는 Ctrl+Shift+P를 눌러 Developer: Reload Window를 입력하여 재시작해 보십시오. 이 과정은 메모리에 잔여해 있던 오래된 파이썬 언어 서버 프로세스를 초기화하여 통신 오류를 해결하는 데 도움을 줍니다.

확장 프로그램이 정상적으로 로드되었는지 확인하는 또 다른 방법은 명령 팔레트를 사용하여 REPL(Read-Eval-Print Loop)을 구동해 보는 것입니다. Python: Start REPL 명령어를 실행했을 때 터미널에 대화형 쉘이 정상적으로 뜨고 >>> 프롬프트가 활성화된다면 확장 기능이 완벽하게 활성화된 상태입니다. 만약 이 명령어를 찾을 수 없다는 메시지가 뜨거나 실행해도 아무 반응이 없다면, 확장 프로그램 설치가 완전하지 않거나 VSCode가 확장을 인식하지 못한 상태이므로 해당 확장을 비활성화했다가 다시 설치하는 재설치 작업이 필요합니다. 또한, Pylance와 같은 의존성 확장이 함께 설치되었는지 확인하는 것도 중요합니다. Pylance는 IntelliSense(자동 완성)를 담당하지만, 디버거가 변수 정보를 읽어올 때 이 언어 서버의 데이터를 참조하는 경우가 많기 때문입니다.

Photo by Alicia Christin Gerald on Pexels

올바른 파이썬 인터프리터 선택 및 경로 지정

VSCode 파이썬 디버깅 설정에서 가장 많이 실수하는 부분은 잘못된 파이썬 인터프리터를 사용하는 것입니다. 시스템에 설치된 전역 파이썬과 프로젝트별로 생성한 가상 환경의 파이썬은 서로 다른 라이브러리와 버전을 가지고 있습니다. 예를 들어, 가상 환경에 설치된 requests 라이브러리를 사용하는 코드를 디버깅하려는데 인터프리터가 시스템 전역 파이썬으로 설정되어 있다면, 브레이크포인트를 잡더라도 모듈을 찾지 못해 실행이 즉시 멈추거나, 디버거는 실행되지만 코드 내부에서 ImportError가 발생하여 예기치 않은 경로로 빠져나갈 수 있습니다. 이는 VSCode가 현재 파일을 실행할 때 어떤 파이썬 executable을 사용해야 할지 혼란을 겪기 때문입니다.

인터프리터를 확인하려면 하단 상태바의 우측에 있는 Python 버전 표시를 클릭하거나, 명령 팔레트에서 Python: Select Interpreter를 입력합니다. 여기서 프로젝트의 루트 폴더에 있는 venv 폴더 내의 파이썬 실행 파일을 선택해야 합니다. 윈도우 사용자라면 venv\Scripts\python.exe, 맥이나 리눅스 사용자라면 venv/bin/python 경로를 가진 항목을 선택해야 합니다. 최근 VSCode는 .venv 표준 폴더나 conda 환경도 자동으로 감지하여 목록에 띄워주므로, 목록에 아이콘(가상 환경은 작은 폴더 아이콘)이 표시된 항목을 선택하는 것이 가장 정확합니다.

터미널에서 직접 현재 사용 중인 파이썬 경로를 확인하고 싶다면 아래 명령어를 사용하여 VSCode가 인식하고 있는 경로와 일치하는지 비교해야 합니다. 터미널의 경로와 VSCode 상태바에 표시된 경로가 다르다면, 터미널에서는 가상 환경이 활성화되어 있지만 VSCode 디버거는 시스템 파이썬을 바라보고 있다는 뜻이므로 반드시 수정해야 합니다.

# macOS / Linux
which python3

# Windows
where python

또한, settings.json 파일을 통해 인터프리터 경로를 강제로