[Python] VSCode 시작하기 - 가상환경(.venv) 설정과 프로젝트 실행

1. Visual Studio Code 특징

1) 프로젝트 단위 실행

• 이클립스와 달리, 프로젝트마다 VSCode를 별도로 열어야 함.
• 이클립스는 하나의 워크스페이스 안에서 여러 프로젝트를 동시에 관리할 수 있지만, VSCode는 폴더 단위로 작업 공간이 구성되기 때문에 프로젝트마다 해당 폴더를 별도로 열어야 함.

 

2) Connect to

• 외부 연결 또는 클라우드 환경에 접속하는 기능.
• 원격 서버(SSH), 컨테이너(Docker), 클라우드 환경 등에 접속하여 로컬에서 작업하는 것처럼 원격 환경에서 개발할 수 있게 해줌.
• Remote - SSH, Dev Containers, GitHub Codespaces 등의 Extension과 함께 사용됨.

 

3) Extension

• VSCode 자체는 텍스트 편집기에 가깝고, Extension은 특정 언어나 기능을 사용할 수 있도록 도와주는 플러그인
• 환경만 제공하므로, Java는 JDK를, 파이썬은 Python 인터프리터를 별도로 설치해야 함.
• 즉, 언어 실행에 필요한 런타임(JDK, Python 등)은 Extension과 별개로 직접 설치해야 함.
• 좌측 사이드바의 Extensions 아이콘(Ctrl+Shift+X)을 통해 설치 및 관리할 수 있음.

 

4) Command Palette

• VSCode의 모든 명령어를 검색하고 실행할 수 있는 기능
• View 메뉴 클릭 또는 상단 검색창에 >를 입력하거나, 단축키 Ctrl+Shift+P로 실행.
• 메뉴를 일일이 탐색하지 않고도 원하는 기능을 빠르게 찾아 실행할 수 있음.
• 예: Python: Select Interpreter, Git: Clone, Terminal: Create New Terminal 등

 

2. 파이썬 가상환경(.venv) 개념

• 프로젝트마다 독립적인 패키지 환경을 구성할 수 있는 기능.
• 프로젝트 간 패키지 버전 충돌 없이 각각의 환경을 유지할 수 있음.
• 파이썬은 자바(pom.xml, build.gradle)와 달리 별도의 의존성 설정 파일이 없어 가상환경(.venv)을 생성하여 프로젝트별 패키지를 관리함.
• 가상환경 내 설치된 패키지 목록은 pip freeze > requirements.txt 명령어로 저장하여 공유할 수 있음.

 

3. VSCode에서 파이썬 프로젝트 실행하기

1) 가상환경 생성 및 설정

• 가상환경 생성 : Command Palette에서 Python:Select Interpreter → Create Virtual Environment → venv → 파이썬 버전 선택(3.13.13) → 가상환경명 입력
• 생성 후 프로젝트 루트에 .venv 폴더가 생성되며, VSCode가 자동으로 해당 인터프리터를 선택함.
• 패키지 설치는 pip install 패키지명 명령어를 사용함.
• 설치된 패키지 확인: pip list
• 패키지 목록 관리 (requirements.txt) : 협업하거나 다른 환경에서 동일한 세팅을 재현할 때 requirements.txt를 공유하면 패키지를 일일이 설치하지 않아도 됨.

  명령어	설명
  pip freeze > requirements.txt	현재 설치된 패키지 목록을 파일로 저장
  pip install -r requirements.txt	txt 기반으로 패키지 일괄 설치 (협업 시 환경 동기화)
  pip download -d packages/ -r requirements.txt	패키지 설치파일(.whl, tar.gz)을 로컬에 다운로드 (오프라인 환경 대비)
  pip install --no-index --find-links=packages/ -r requirements.txt	다운로드된 파일로 오프라인 설치

 

2) 터미널 실행

• VSCode 내 터미널 실행 시 가상환경이 자동으로 활성화되는지 확인해야 함.
• 가상환경을 활성화할 때 내부적으로 .venv\Scripts\Activate.ps1스크립트가 자동 실행됨.
• 활성화된 경우 터미널 프롬프트 앞에 (.venv)가 표시됨.

 

 

3) 스크립트 실행 오류발생 시 해결 방법

가상환경 활성화 시도
→ Activate.ps1 실행 필요
→ Windows 기본 보안 정책이 차단 (Restricted)
→ Set-ExecutionPolicy RemoteSigned 로 정책 완화
→ 가상환경 정상 활성화 → (.venv) 표시 확인

(1) 오류 발생 원인

• Windows는 악성 스크립트 실행을 막기 위해 PowerShell 스크립트(.ps1 파일)의 실행을 기본적으로 차단하는 보안 정책을 갖고 있음. 이 정책을 ExecutionPolicy(실행 정책) 라고 함.
• 가상환경 활성화 시 .venv\\Scripts\\Activate.ps1이 실행되어야 하는데, Windows 기본 보안 정책이 이를 차단하여 가상환경 활성화가 되지 않음.

(2) ExecutionPolicy 주요 종류

정책	설명
Restricted	모든 스크립트 실행 차단 (Windows 기본값)
RemoteSigned	로컬 스크립트는 허용, 인터넷에서 받은 파일은 서명 필요
Unrestricted	모든 스크립트 허용 (보안상 비추천)

 

(3) 해결 방법

• 터미널에서 Set-ExecutionPolicy RemoteSigned 입력
• -Scope CurrentUser 옵션을 추가하면 해당 사용자에게만 정책이 적용되므로, 시스템 전체에 영향을 주지 않아 더 안전함.
• 대소문자 상관 없음

Set-ExecutionPolicy RemoteSigned
# 현재 사용자에게만 적용할 경우:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

 

3) 파일 생성 및 실행

(1) .ipynb 파일 (주피터 노트북)

• 파일 생성후 가상환경 선택
• 처음 실행 시 ipykernel 등 필요한 패키지 설치 안내가 뜨며, 설치 후 사용 가능.
• 셀 단위로 코드를 실행할 수 있어 데이터 분석이나 실습에 적합함.
• 실행 결과가 셀 바로 아래에 출력되어 단계별 확인이 용이함.

셀 종류	용도
Code 셀	실제 실행할 코드 작성 (Shift+Enter로 실행)
Markdown 셀	문서화, Outline에서 특정 위치로 이동 가능

 

(2) .py 파일 (일반 파이썬 파일)

• 일반적인 파이썬 스크립트 파일로, 전체 코드를 한 번에 실행함.
• 실행 방법:
  • 우측 상단의 ▶ (Run) 버튼 클릭
  • 터미널에서 python 파일명.py 명령어 직접 입력
  • 단축키 Ctrl+F5 (디버깅 없이 실행)
• .ipynb와 달리 셀 구분 없이 위에서 아래로 순차 실행됨.
• 실제 서비스 배포나 모듈화된 프로젝트 개발에 적합함.