초보자를 위한 개발 환경 구축: Windows에서 VS Code로 Python 개발 시작하기(설치·가상환경·첫 실행까지)

처음 개발을 시작할 때 가장 많이 막히는 순간은 “코드는 어디서 쓰지?”가 아니라, 어디까지 설치해야 정상인지가 불분명할 때입니다. 특히 Windows에서는 Python, VS Code, 터미널, 가상환경이 한 번에 정리되지 않으면 실행이 안 되거나 버전이 섞여서 고생하죠. 오늘은 개발 초보자 기준으로, 딱 필요한 것만 깔끔하게 세팅해서 첫 실행까지 가는 흐름을 정리해드립니다.

1) 준비물 체크: 내가 지금 뭘 설치해야 하나?

• Python(인터프리터): 실제로 파이썬 코드를 실행하는 엔진
• VS Code(편집기): 코드를 쓰고 실행을 돕는 작업 공간
• 가상환경(venv): 프로젝트별로 라이브러리를 분리해 충돌을 막는 장치
• 터미널: 명령어로 설치/실행을 하는 창(Windows에서는 PowerShell을 주로 사용)

2) Python 설치(Windows)

설치할 때 꼭 확인할 것 2가지

1. 설치 화면에서 “Add Python to PATH” 체크

• 체크 안 하면 터미널에서 python 명령이 안 먹는 경우가 많습니다.

1. 설치 후 터미널(PowerShell)에서 버전 확인 버전이 출력되면 1차 통과입니다. 만약 python 대신 py가 동작한다면, Windows 환경에 따라 그럴 수 있어요. 이 경우:

py --version

3) VS Code 설치 후, Python 개발에 필요한 확장

VS Code는 설치만으로도 편집은 가능하지만, Python 개발은 확장을 붙이면 체감이 확 달라집니다.

추천 확장(필수급)

• Python: 실행/디버깅/문법 지원의 핵심
• Pylance: 자동완성, 타입 힌트 등 코드 작성이 빨라짐 설치 후 VS Code를 재시작하면 적용이 안정적입니다.

4) 프로젝트 폴더 만들기 + 가상환경(venv) 구성

이 단계가 개발 습관을 결정합니다. 프로젝트마다 가상환경을 만들면 “어제는 되던 게 오늘은 안 됨” 같은 상황이 줄어듭니다.

1) 폴더 생성 & VS Code로 열기

예: C:\dev\hello-python 폴더를 만들고 VS Code에서 폴더 열기로 엽니다.

2) 터미널 열기

VS Code 상단 메뉴에서 터미널을 열어 PowerShell이 뜨는지 확인합니다.

3) 가상환경 생성

python -m venv .venv

4) 가상환경 활성화

.\.venv\Scripts\Activate.ps1

성공하면 프롬프트 앞에 (.venv) 같은 표시가 붙습니다.

만약 실행 정책 때문에 막히면, PowerShell에서 아래를 한 번만 실행하고 다시 활성화해보세요(환경에 따라 필요할 수도, 아닐 수도 있습니다).

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

5) VS Code에서 인터프리터 선택(중요)

가상환경을 만들었어도 VS Code가 다른 Python을 잡으면 실행이 꼬입니다.

확인 방법

• VS Code에서 Python 인터프리터 선택 메뉴를 열어 .venv 경로가 포함된 Python을 선택합니다.

이게 맞아야 pip install도 프로젝트 전용으로 깔끔하게 들어갑니다.

6) 첫 실행: “Hello, Python!”부터 제대로

프로젝트 폴더에 main.py 파일을 만들고 아래를 입력합니다.

def greet(name: str) -> None:
    print(f"안녕하세요, {name}님! VS Code에서 Python 개발 시작 완료!")

if __name__ == "__main__":
    greet("초보 개발자")

실행(터미널)

python main.py

정상이라면 인사 문장이 출력됩니다. 여기까지 됐다면 설치·가상환경·실행의 핵심 파이프라인이 완성된 겁니다.

7) 초보자가 자주 겪는 문제 3가지(빠른 처방)

1) python 명령이 인식되지 않음

• Python 설치 시 PATH 체크가 빠졌을 가능성
• py main.py로 실행이 되는지 확인해보세요.

2) 라이브러리를 설치했는데 실행 시 못 찾는다고 함

• 가상환경이 활성화되지 않았거나, VS Code 인터프리터가 .venv가 아닐 수 있습니다.
• (.venv) 표시 확인 → 인터프리터 재선택 순으로 점검하세요.

3) VS Code에서 실행은 되는데 터미널 실행이 다름

• VS Code의 “실행 버튼”이 다른 인터프리터를 잡았을 가능성이 큽니다.
• 항상 인터프리터가 .venv인지부터 맞추면 해결되는 경우가 많습니다.

마무리: 오늘 세팅이 내일의 속도를 만든다

처음엔 번거롭지만, 프로젝트 폴더마다 venv 만들기 → VS Code에서 인터프리터 맞추기 → 터미널로 실행하기 이 루틴이 잡히면 개발이 훨씬 편해집니다. 다음 단계로는 requests 같은 라이브러리 설치, 디버깅 브레이크포인트 사용, 포매터(Black) 적용까지 확장해보면 좋아요.