VSCode 파이썬 개발 환경 설정 완벽 가이드 (설치부터 실행까지 쉽게 정리)

Pylance 확장이 제대로 작동하면 코드 입력 시 자동 완성이 뜨고, 문법을 잘못 쓰면 밑줄이 생기는 현상은 정상적인 상태이다. Windows에서는 2-2 명령어가 설치 환경에 따라 py 대신 python을 사용해야 할 수 있으며 macOS나 Linux에서는 python3을 사용하는 경우가 일반적이다. 터미널에서 저장 경로를 정확히 맞추지 않으면 실행이 안 될 수 있어 저장 경로를 확실히 맞추고 사용해야 한다.

자주 하는 실수와 해결법으로는 먼저 파일을 저장하지 않는 경우가 있다. 코드를 고친 뒤 실행해도 변화가 없으면 저장이 안 된 것이니 Ctrl S로 저장한 뒤 재실행하면 된다. 자동 저장을 켜 두면 이러한 실수를 줄일 수 있다. 확장자를 잘못 저장하는 경우도 흔하다. .txt로 저장하면 Python이 글 파일로 인식해 실행되지 않으므로 반드시 .py로 저장해야 한다. 따옴표를 빠뜨리는 경우에는 문자열을 찾다가 NameError가 발생하므로 문자열은 반드시 " " 또는 ' ' 안에 넣어야 한다.

다음으로 Python 인터프리터의 선택과 관리에 대해 다룬다. 인터프리터란 작성한 코드를 실제로 실행하는 프로그램이며, 한 컴퓨터에는 여러 버전의 Python이 설치될 수 있고 프로젝트마다 가상환경(venv/conda)을 달리 쓰는 경우가 많아 VSCode에서는 사용할 인터프리터를 꼭 지정해야 한다. 인터프리터 확인은 상태 표시줄 하단의 Python 3.x.x 또는 Select Interpreter를 통해 확인할 수 있으며 보이지 않으면 Command Palette에서 Python: Select Interpreter를 실행해 선택한다. 인터프리터를 변경하려면 하단의 항목을 클릭하거나, Ctrl Shift P로 명령 팔레트를 열고 Python: Select Interpreter를 입력해 목록에서 선택하거나 Enter interpreter path로 직접 경로를 지정한다.

선택 가능한 인터프리터 유형으로는 시스템(글로벌) Python, 가상환경 인터프리터, Conda 환경이 있다. 시스템 Python은 전역적으로 설치된 인터프리터이고, 간단한 스크립트에 적합하나 프로젝트별 패키지 충돌을 피하려면 가상환경을 권장한다. 가상환경 인터프리터는 프로젝트 전용으로 만든 실행 파일이며 보통 폴더명이나 .venv 표기로 나타난다. Conda 환경은 데이터 과학에 유리한 conda 환경을 활용할 때 선택한다. 처음이고 특별한 환경이 없다면 시스템 Python 3.x를 선택하고, 프로젝트별로 격리된 환경을 쓰고 있다면 해당 가상환경을 반드시 선택한다. Anaconda를 쓴다면 base보다 프로젝트용 named conda 환경을 선택하는 것이 안전하다.

인터프리터 선택 시 자주 생기는 문제로는 목록이 비어 있는 경우가 있다. 이때는 터미널에서 Python 설치 여부를 확인하고, VSCode에 Python 확장이 설치되어 있으며 활성화되어 있는지 확인한 뒤 VSCode를 재시작하거나 개발 창을 재로드한다. 작업 폴더가 열려 있는지 확인하고 WSL/Remote/Container 환경을 쓰는 경우 로컬과 다른 환경인지도 확인한다. 원하는 버전이 보이지 않는 경우에는 Python: Select Interpreter에서 Enter interpreter path를 선택해 Find로 경로를 직접 찾거나 터미널에서 where 또는 which 명령으로 경로를 확인해 붙여넣는다. 가상환경이 자동으로 인식되지 않는 경우에는 프로젝트 루트에 가상환경이 있는지 확인하고, 필요 시 Enter interpreter path로 직접 선택한 뒤 VSCode를 재시작한다.

가상환경(venv) 설정은 권장된다. 가상환경은 프로젝트마다 필요한 패키지와 버전을 독립적으로 관리할 수 있게 해 주며, 라이브러리 충돌을 막고 팀 간 동일한 환경 구성을 공유하기 용이하다. 가상환경을 설정하는 방법은 운영체제별 차이가 있어 초보자는 혼동하기 쉽지만, 관련 사이트에서 정리된 내용을 참고하면 이해가 쉬워진다. 설정 방법은 설정 파일이나 인터프리터 자동 인식 등을 통해 진행되며, 필요하면 Python: Select Interpreter에서 경로를 직접 지정해 적용한다.