Python 가상환경(venv) 완벽 정리

이 글에서 다루는 내용

Python의 venv 모듈을 사용해 프로젝트별로 독립된 환경을 만들고 관리하는 전 과정을 정리합니다. 의존성 충돌은 Python 초보자가 가장 자주 부딪히는 벽이지만, venv 하나만 제대로 써도 95%는 해결됩니다. 활성화, 패키지 설치, 공유, 삭제, pyenv와의 조합, IDE 통합까지 실무 패턴 중심으로 다룹니다.

"한 컴퓨터에 Python을 하나만 깔아 쓰면 안 되나?"라는 의문이 들 수 있습니다. 가능은 하지만 프로젝트가 두 개를 넘어가는 순간 거의 반드시 깨집니다. 어떤 라이브러리는 NumPy 1.x를 요구하고, 새 프로젝트는 2.x를 쓰고, OS가 관리하는 시스템 Python까지 같이 망가져 셸 명령 일부가 동작하지 않는 일이 흔합니다. venv는 이 위험을 폴더 단위로 가둬, 한 프로젝트의 환경 변경이 다른 프로젝트에 영향을 주지 않게 만듭니다.

---

1. venv가 해결하는 문제

1-1. 왜 가상환경이 필요한가

시스템 전역 Python에 pip install로 라이브러리를 계속 깔면, 결국 아래 상황이 옵니다.

• 프로젝트 A는 Django 4.x가 필요한데 B는 3.x만 지원
• 어느 날 requests 버전이 올라가면서 오래된 스크립트가 전부 깨짐
• 운영체제가 관리하는 Python을 건드려서 시스템 도구까지 꼬임
• 최근 Ubuntu·macOS는 시스템 pip 사용을 막아 externally-managed-environment 오류가 나기도 함

venv는 프로젝트별로 격리된 site-packages를 만들어 이 문제를 원천 차단합니다. 한 폴더 안에서 끝나기 때문에 깨끗하게 지우고 다시 만들기도 쉽습니다.

venv가 만드는 격리 구조 시스템 Python OS 기본, 손대지 않음 프로젝트 A .venv/ Django 4.2, requests 2.31 프로젝트 B .venv/ Django 3.2, pandas 1.5 프로젝트 C .venv/ FastAPI 0.110, pydantic 2

1-2. venv vs 다른 도구 비교

도구	장점	단점
venv	표준 내장, 추가 설치 없음	Python 버전 자체는 관리 못함
virtualenv	venv보다 빠르고 옵션 많음	외부 패키지
pyenv	Python 버전 관리에 특화	venv와 조합 필요
poetry	의존성 lock, 빌드 통합	학습 곡선, 팀 합의 필요
conda	데이터 사이언스 생태계	용량, 속도 이슈
uv	압도적으로 빠른 설치	신규 도구, 생태계 정착 중

💡 "정석대로" 가고 싶다면 pyenv + venv 조합이 가장 안정적입니다. 이 글은 이 조합을 기준으로 합니다. 속도가 가장 중요하다면 같은 venv 인터페이스를 따르는 uv도 고려해볼 만합니다.

1-3. 가상환경 안에는 무엇이 들어가나

python -m venv .venv를 실행하면 .venv 폴더 안에 작은 디렉터리 구조가 생깁니다. bin/(Windows는 Scripts/)에는 그 환경 전용 python·pip 바이너리 심볼릭 링크가, lib/pythonX.Y/site-packages/에는 이 환경에 설치된 패키지가 들어갑니다. 활성화한다는 것은 결국 PATH 앞에 이 bin/을 끼워 넣어, python·pip 명령이 시스템 대신 이 폴더의 바이너리를 호출하게 만드는 일입니다. 그래서 .venv 폴더만 통째로 지우면 환경이 완전히 사라집니다.

---

2. venv 기본 사용법

2-1. 가상환경 생성

프로젝트 폴더에 들어가 .venv라는 이름으로 만드는 것이 관례입니다. 점(.)으로 시작해 숨김 처리되고, IDE·린터·CI 도구 대부분이 이 이름을 기본값으로 인식합니다.

cd ~/dev/my-project
python3 -m venv .venv

.venv 폴더가 생성되고 안에 Python 바이너리 링크, pip, 빈 site-packages가 준비됩니다. 생성 자체는 1~2초이면 끝납니다.

2-2. 활성화

OS별로 활성화 스크립트가 다릅니다.

# macOS / Linux / WSL
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

프롬프트 앞에 (.venv)가 붙으면 성공입니다. which python으로 실제 바이너리 경로까지 확인해두면 안전합니다.

(.venv) $ which python
/home/user/dev/my-project/.venv/bin/python

2-3. 비활성화

deactivate

활성화/비활성화는 언제든 반복할 수 있습니다. 셸 세션이 끝나면(터미널 창을 닫으면) 자동으로 비활성화 상태가 되니, 신경 쓰지 않아도 됩니다.

2-4. IDE에서 자동으로 인식하기

VS Code는 폴더 안의 .venv/를 자동 감지해 인터프리터로 잡습니다. PyCharm은 "Project Interpreter" 설정에서 .venv 경로를 한 번 지정해두면 다음부터 자동 적용됩니다. IDE 안의 통합 터미널을 열면 활성화도 자동으로 처리해 줘서, 굳이 source 명령을 손으로 칠 일이 줄어듭니다.

---

3. 의존성 관리

3-1. 패키지 설치

활성화된 상태에서 pip install은 그 가상환경에만 설치됩니다. 시스템 Python에는 어떤 영향도 가지 않습니다.

pip install requests fastapi uvicorn

3-2. requirements.txt 추출

현재 설치된 버전을 그대로 파일로 남깁니다. 협업자가 동일 환경을 만들 때 그대로 사용합니다.

pip freeze > requirements.txt

requirements.txt 예시

fastapi==0.110.0
requests==2.31.0
uvicorn==0.27.1

3-3. 다른 환경에서 복원

협업자나 배포 서버에서 동일 환경을 재현할 때 사용합니다. requirements.txt가 같다면 동일한 패키지 버전 조합이 보장됩니다.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3-4. requirements.txt의 한계와 lock 파일

pip freeze는 설치된 모든 패키지를 기록합니다. 직접 쓰는 라이브러리뿐 아니라 그 의존성으로 따라 깔린 패키지까지 다 들어가서, 어느 줄이 핵심이고 어느 줄이 부차적인지 구분이 어렵습니다. 또 환경에 따라 서로 다른 부 의존성이 끼어들 수 있어, "내 컴퓨터에서는 되는데 서버에선 안 된다"라는 상황이 종종 생깁니다. 직접 쓰는 패키지만 별도 파일(requirements.in)에 적고, pip-tools나 poetry로 lock 파일을 만드는 방법이 더 안전합니다.

⚠️ 회사 코드라면 처음부터 pip-tools나 poetry 도입을 고려하세요. requirements.txt만으로는 장기적으로 재현성이 약합니다.

---

4. pyenv와 조합해 Python 버전까지 고정

4-1. pyenv 설치

curl https://pyenv.run | bash

~/.bashrc 혹은 ~/.zshrc에 PATH와 init 구문을 추가한 뒤 셸을 재시작합니다. 설치 직후 표시되는 안내 문구를 그대로 복사해 넣으면 됩니다.

4-2. 특정 버전 설치와 지정

pyenv install 3.12.2
cd ~/dev/my-project
pyenv local 3.12.2

.python-version 파일이 생성되고, 해당 폴더에서는 지정한 파이썬이 기본이 됩니다. 이 파일은 git에 커밋해 팀원과 동일한 Python 버전을 공유할 수 있습니다.

4-3. 그 버전으로 venv 만들기

python -m venv .venv
source .venv/bin/activate
python --version

출력은 3.12.2가 되어야 합니다. 프로젝트마다 Python 마이너 버전까지 고정할 수 있게 됩니다. 이렇게 두면 OS가 업그레이드되면서 시스템 Python이 바뀌어도 프로젝트 안의 환경은 그대로 남습니다.

---

5. 자주 쓰는 실무 패턴

1. 새 프로젝트 시작하자마자 python -m venv .venv 먼저 실행
2. .gitignore에 .venv/ 추가 (절대 커밋하지 않음 — 폴더 크기와 OS 의존성 때문)
3. README에 python -m venv .venv && pip install -r requirements.txt 명시
4. 환경이 꼬였다면 rm -rf .venv 후 재생성 — 빠르고 안전
5. CI 파이프라인에서도 동일 명령으로 재현, 캐시는 .venv가 아니라 ~/.cache/pip 디렉터리에
6. 새 라이브러리를 추가했다면 그 자리에서 바로 pip freeze > requirements.txt로 갱신해 PR에 포함

---

트러블슈팅

문제 1: python: command not found

시스템에 따라 기본 명령이 python3일 수 있습니다.

python3 -m venv .venv

또는 alias를 지정합니다.

echo 'alias python=python3' >> ~/.bashrc
source ~/.bashrc

문제 2: PowerShell에서 스크립트 실행 정책 오류

cannot be loaded because running scripts is disabled on this system

현재 사용자만 허용하도록 변경합니다.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

문제 3: pip install이 매우 느림

국내 미러를 지정하면 체감 속도가 크게 빨라집니다.

pip install -i https://mirror.kakao.com/pypi/simple <package>

영구 설정은 ~/.pip/pip.conf에 기록합니다.

[global]
index-url = https://mirror.kakao.com/pypi/simple

문제 4: externally-managed-environment 오류

최신 macOS·Ubuntu에서 시스템 Python에 직접 pip install을 시도하면 이 오류가 납니다. 시스템 환경을 보호하기 위한 의도된 차단입니다. 해결책은 단 하나, 그 자리에서 venv를 만들어 그 안에서 설치하는 것입니다.

python3 -m venv .venv
source .venv/bin/activate
pip install <package>

---

마무리

venv는 기능이 많지 않지만, 이 "심플함"이 오히려 가장 큰 장점입니다. 표준에 들어가 있어서 설치할 필요도 없고, CI와 서버 어디서나 똑같이 동작합니다. Python을 오래 쓸 거라면 첫 프로젝트부터 습관처럼 python -m venv .venv를 적어두는 것을 추천합니다. 팀 단위 협업과 재현성 요구가 강해지면 그때 pip-tools나 poetry로 자연스럽게 한 단계 올라갈 수 있습니다.

• 공식 문서: https://docs.python.org/ko/3/library/venv.html
• 다음 글: Python 가상환경 Anaconda 완벽 정리

함께 읽으면 좋은 글

• WSL2 설치와 Ubuntu 초기 세팅 가이드
• VS Code 개발 환경 최적화 세팅