파이썬 가상환경 설정 방법: VSCode 연동까지 한 번에 끝내기
가상환경을 만들었는데 VSCode 터미널에서는 계속 다른 파이썬이 잡히는 경우, 실제로 꽤 흔합니다. 이 글에서는 명령어 자체보다 “왜 안 되는지”까지 같이 짚어보겠습니다.
Table of Contents
파이썬 가상환경이 필요한 이유
프로젝트 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_projectVSCode를 쓸 계획이라면 여기서 바로 code . 명령으로 폴더 전체를 열어두는 걸 추천합니다. 파일 하나만 따로 여는 방식은 뒤에서 설명할 인터프리터 인식 문제의 원인이 됩니다.
가상환경 생성 명령어
프로젝트 폴더 안에서 아래 명령을 실행합니다.
python -m venv .venv.venv는 가상환경 폴더 이름입니다. venv나 myenv 등 원하는 이름으로 바꿔도 무방하지만, .venv는 셸에서 숨김 처리되면서도 의미가 명확해 실무에서 가장 널리 쓰입니다.
OS별 가상환경 활성화 방법
활성화 명령은 운영체제에 따라 다릅니다. 이 부분에서 명령어를 헷갈려서 “명령을 찾을 수 없음” 오류를 겪는 경우가 실제로 많습니다.
| 운영체제 | 활성화 명령 |
|---|---|
| Windows (CMD/PowerShell) | .venvScriptsactivate |
| macOS / Linux | source .venv/bin/activate |
활성화에 성공하면 터미널 프롬프트 앞에 (.venv)처럼 환경 이름이 표시됩니다. 이 표시가 안 뜬다면 활성화가 제대로 안 된 것이니 명령어와 경로를 다시 확인해야 합니다.
PowerShell에서 activate가 막힐 때
윈도우 PowerShell에서는 보안 정책 때문에 Activate.ps1 스크립트 실행이 거부되는 경우가 자주 발생합니다. “이 시스템에서 스크립트를 실행할 수 없습니다” 같은 오류가 뜬다면, PowerShell을 관리자 권한으로 열고 아래 명령을 입력합니다.
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned는 로컬에서 작성한 스크립트는 허용하고 인터넷에서 받은 서명 없는 스크립트만 막는 방식이라, 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와 활성화 명령 체계가 다르므로, 팀에서 이미 쓰고 있다면 해당 도구의 공식 문서를 따로 확인하는 게 안전합니다.
자주 묻는 질문
가상환경 폴더 이름은 꼭 .venv여야 하나요?
아닙니다. venv, myenv 등 원하는 이름을 써도 됩니다. 다만 .venv는 셸에서 자동으로 숨겨지고 관례적으로 널리 쓰이는 이름이라, 특별한 이유가 없다면 그대로 사용하는 걸 권장합니다.
가상환경 폴더도 깃허브에 올려야 하나요?
아니요, 올리면 안 됩니다. .venv 폴더는 용량이 크고 내 컴퓨터 경로에 종속된 파일들이 들어있어서, .gitignore에 추가해 제외하고 대신 requirements.txt만 커밋하는 게 표준적인 방식입니다.
가상환경을 활성화하지 않아도 특정 환경의 파이썬을 쓸 수 있나요?
가능합니다. 가상환경 안의 파이썬 인터프리터 전체 경로를 직접 지정해 실행하면 활성화 과정 없이도 그 환경의 패키지를 사용할 수 있습니다. 다만 매번 경로를 입력해야 해서, 일반적인 개발 작업에서는 활성화 방식이 더 편리합니다.
