파이썬 가상환경 설정 방법: VSCode 연동까지 한 번에 끝내기

가상환경을 만들었는데 VSCode 터미널에서는 계속 다른 파이썬이 잡히는 경우, 실제로 꽤 흔합니다. 이 글에서는 명령어 자체보다 “왜 안 되는지”까지 같이 짚어보겠습니다.

파이썬 가상환경이 필요한 이유

프로젝트 A는 Django 3.x, 프로젝트 B는 Django 5.x가 필요한 상황을 겪어본 적 있으신가요. 전역 환경 하나로는 둘 다 만족시킬 수 없습니다. 가상환경은 프로젝트마다 독립된 패키지 공간을 만들어 이 문제를 원천적으로 없애줍니다.

핵심만 정리하면 이렇습니다.

• 의존성 격리: 프로젝트별로 다른 버전의 라이브러리 사용 가능
• 시스템 보호: 운영체제에 딸린 파이썬을 건드리지 않음
• 재현성: 동료나 미래의 나 자신이 똑같은 환경을 다시 만들 수 있음

Python 3.3 이상부터는 venv 모듈이 표준 라이브러리에 기본 포함되어 있어서, 별도 설치 없이 바로 사용할 수 있습니다.

가상환경 생성 전 준비: 파이썬 버전 확인

터미널을 열고 아래 명령으로 설치 여부와 버전을 먼저 확인합니다.

“`

python –version

“`

또는

“`

python3 –version

“`

여기서 3.3 이상이 확인되면 바로 다음 단계로 넘어가면 됩니다. 윈도우라면 python.org 공식 사이트에서 설치할 때 “Add Python to PATH” 옵션을 반드시 체크해야, 이후 명령어 인식 문제를 피할 수 있습니다.

프로젝트 폴더 생성 및 이동

가상환경은 프로젝트 폴더 안에서 만드는 것이 원칙입니다. 홈 디렉터리나 시스템 루트에 만들면 나중에 여러 프로젝트의 가상환경이 뒤섞여 관리가 꼬입니다.

“`

mkdir my_project

cd my_project

“`

VSCode를 쓸 계획이라면 여기서 바로 code . 명령으로 폴더 전체를 열어두는 걸 추천합니다. 파일 하나만 따로 여는 방식은 뒤에서 설명할 인터프리터 인식 문제의 원인이 됩니다.

가상환경 생성 명령어

프로젝트 폴더 안에서 아래 명령을 실행합니다.

“`

python -m venv .venv

“`

.venv는 가상환경 폴더 이름입니다. venv나 myenv 등 원하는 이름으로 바꿔도 무방하지만, .venv는 셸에서 숨김 처리되면서도 의미가 명확해 실무에서 가장 널리 쓰입니다.

OS별 가상환경 활성화 방법

활성화 명령은 운영체제에 따라 다릅니다. 이 부분에서 명령어를 헷갈려서 “명령을 찾을 수 없음” 오류를 겪는 경우가 실제로 많습니다.

운영체제	활성화 명령
Windows (CMD/PowerShell)	.venv\Scripts\activate
macOS / Linux	source .venv/bin/activate

활성화에 성공하면 터미널 프롬프트 앞에 (.venv)처럼 환경 이름이 표시됩니다. 이 표시가 안 뜬다면 활성화가 제대로 안 된 것이니 명령어와 경로를 다시 확인해야 합니다.

PowerShell에서 activate가 막힐 때

윈도우 PowerShell에서는 보안 정책 때문에 Activate.ps1 스크립트 실행이 거부되는 경우가 자주 발생합니다. “이 시스템에서 스크립트를 실행할 수 없습니다” 같은 오류가 뜬다면, PowerShell을 관리자 권한으로 열고 아래 명령을 입력합니다.

“`

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

“`

RemoteSigned는 로컬에서 작성한 스크립트는 허용하고 인터넷에서 받은 서명 없는 스크립트만 막는 방식이라, Unrestricted보다 보안상 더 안전한 선택지입니다.

VSCode에서 가상환경 연결하기

터미널에서 가상환경을 만들었어도 VSCode가 자동으로 인식하지 못하는 경우가 있습니다. 이때는 수동으로 연결해줘야 합니다.

• Ctrl+Shift+P (macOS는 Cmd+Shift+P)로 명령 팔레트를 엽니다
• Python: Select Interpreter를 입력하고 선택합니다
• 목록에 .venv 항목이 보이면 선택하고, 안 보이면 “인터프리터 경로 입력”을 눌러 .venv/Scripts/python.exe(윈도우) 또는 .venv/bin/python(macOS/Linux) 경로를 직접 지정합니다

설정 후 VSCode 하단 상태 표시줄에 선택한 인터프리터 정보가 표시되면 정상 연결된 것입니다. 팀 프로젝트라면 .vscode/settings.json에 아래처럼 경로를 고정해두면 팀원 전체가 매번 수동으로 선택할 필요가 없어집니다.

“`

{ “python.defaultInterpreterPath”: “${workspaceFolder}/.venv/bin/python” }

“`

가상환경 표시는 뜨는데 실제로는 다른 파이썬이 실행되는 경우

터미널 프롬프트에 (.venv)는 떠 있는데 import 오류가 계속 나거나 엉뚱한 패키지 목록이 보이는 경우, 인터프리터 설정과 터미널 셸이 서로 다른 파이썬을 가리키고 있을 가능성이 높습니다. 확인 방법은 다음과 같습니다.

• macOS/Linux: which python
• Windows: where python

출력된 경로가 프로젝트 폴더 안의 .venv를 가리키지 않는다면, VSCode 기본 터미널 설정(PowerShell/CMD/bash)과 인터프리터 선택이 어긋나 있는 것입니다. 이 경우 터미널을 완전히 새로 열거나, 인터프리터를 다시 선택해 재연결하면 대부분 해결됩니다.

패키지 설치와 requirements.txt

가상환경이 활성화된 상태에서 필요한 패키지를 설치합니다.

“`

pip install requests

pip list

“`

다른 컴퓨터나 팀원에게 동일한 환경을 전달하려면 아래 순서를 씁니다.

환경 저장

“`

pip freeze > requirements.txt

“`

환경 복제

“`

pip install -r requirements.txt

“`

여기서 주의할 점 하나. pip freeze는 현재 활성화된 환경 기준으로 패키지를 기록하므로, 반드시 가상환경을 활성화한 상태에서 실행해야 합니다. 전역 환경에서 실행하면 이 프로젝트와 무관한 패키지까지 섞여 들어갑니다.

가상환경 비활성화 및 삭제

작업이 끝나면 아래 명령으로 종료합니다.

“`

deactivate

“`

가상환경 자체가 더 이상 필요 없다면 .venv 폴더를 통째로 삭제하면 됩니다. 가상환경은 언제든 재생성 가능한 “일회용” 개념이므로, 삭제 후 문제가 생기면 다시 만들면 그만입니다. 단, VSCode에서 이미 삭제된 경로를 인터프리터로 물고 있을 수 있으니, 삭제 후에는 Python: Select Interpreter로 다른 인터프리터를 다시 선택해줘야 합니다.

참고: venv 외 다른 선택지

프로젝트 성격에 따라 venv가 아닌 다른 도구가 더 맞을 수도 있습니다.

• Conda: 데이터 과학·머신러닝처럼 복잡한 비-파이썬 의존성(예: C 라이브러리)까지 함께 관리해야 할 때
• uv: 패키지 설치 속도를 크게 높이고 싶을 때, venv·pip·pyenv 기능을 하나로 통합

두 도구 모두 venv와 활성화 명령 체계가 다르므로, 팀에서 이미 쓰고 있다면 해당 도구의 공식 문서를 따로 확인하는 게 안전합니다.

자주 묻는 질문

함께 보면 좋은 글

• 파이썬 requests 모듈 크롤링, 200인데 안 나오는 이유
• 파이썬 기초 문법 정리 – 직접 해보니 이 5가지가 핵심이었다
• 자바스크립트 입문 기초 개념 총정리 – 변수부터 DOM까지 한 번에