Python venv 완벽 가이드

CTRL K

venv는 Python 3.3부터 표준 라이브러리에 포함된 가상 환경 생성 도구입니다. 프로젝트별로 독립적인 Python 환경을 만들어 패키지 의존성 충돌을 방지하고, 깔끔한 프로젝트 관리를 가능하게 합니다.

이 가이드를 읽으면 venv를 사용하여 격리된 Python 개발 환경을 생성하고 관리하는 방법을 완전히 이해할 수 있습니다. 또한 가상 환경의 작동 원리와 실무에서의 활용법을 배울 수 있습니다.

개요

배경

왜 가상 환경이 필요한가?

Python 프로젝트를 개발하다 보면 다음과 같은 문제에 직면합니다:

문제 1: 의존성 충돌


# 프로젝트 A: Django 3.2 필요
pip install django==3.2
 
# 프로젝트 B: Django 4.2 필요
pip install django==4.2
# ❌ 프로젝트 A가 깨짐!

문제 2: 시스템 오염


# 전역에 수십 개의 패키지 설치
pip install package1 package2 package3...
# ❌ 시스템 Python 환경이 복잡해짐
# ❌ 어떤 프로젝트가 어떤 패키지를 사용하는지 불명확

문제 3: 재현성 부족


# 팀원 A의 환경
Python 3.9, requests 2.28.0, pandas 1.5.0
 
# 팀원 B의 환경
Python 3.11, requests 2.31.0, pandas 2.0.0
# ❌ "내 컴퓨터에서는 되는데요?" 문제 발생

해결책: 가상 환경

가상 환경은 프로젝트별로 독립된 Python 실행 환경을 제공합니다:


전역 Python
├── 프로젝트 A 가상환경 (Django 3.2)
├── 프로젝트 B 가상환경 (Django 4.2)
└── 프로젝트 C 가상환경 (Flask 2.3)

각 프로젝트가 자신만의 패키지 저장소를 가지므로 충돌이 없습니다.

등장 이전의 방식

Python 3.3 이전에는 외부 도구를 사용했습니다:


# virtualenv 설치 (Python 2 시절)
pip install virtualenv
virtualenv myenv
 
# 또는 pyenv 사용
pyenv virtualenv 3.9.0 myenv

현재는 venv가 표준 라이브러리에 포함되어 별도 설치가 불필요합니다.

동작 원리

핵심 메커니즘

venv는 다음과 같은 방식으로 작동합니다:

1. 디렉토리 구조 생성


myproject/
└── venv/
    ├── bin/          # 실행 파일 (Linux/macOS)
    │   ├── python    # Python 인터프리터 심볼릭 링크
    │   ├── pip       # pip 실행 파일
    │   └── activate  # 활성화 스크립트
    ├── Scripts/      # 실행 파일 (Windows)
    ├── lib/          # 패키지 설치 위치
    │   └── python3.11/
    │       └── site-packages/
    └── pyvenv.cfg    # 환경 설정 파일

2. Python 인터프리터 격리


# 시스템 Python
$ which python
/usr/bin/python3.11
 
# 가상 환경 활성화 후
$ source venv/bin/activate
(venv) $ which python
/home/user/myproject/venv/bin/python
# ✅ 프로젝트 전용 Python 사용

3. 패키지 격리


# 시스템 패키지 경로
>>> import sys
>>> sys.path
['/usr/lib/python3.11', '/usr/lib/python3.11/site-packages']
 
# 가상 환경 패키지 경로
>>> import sys
>>> sys.path
['/home/user/myproject/venv/lib/python3.11/site-packages']
# ✅ 프로젝트 전용 패키지 디렉토리

4. 환경 전환


[시스템 환경]
     ↓ activate
[가상 환경] ← PATH, PYTHONPATH 변경
     ↓ deactivate
[시스템 환경]

시각적 이해


작업 흐름:

1. 가상 환경 생성
   python -m venv myenv
   └─> myenv/ 디렉토리 생성

2. 활성화
   source myenv/bin/activate
   └─> PATH 변경
       └─> python, pip가 가상 환경 것을 가리킴

3. 패키지 설치
   pip install requests
   └─> myenv/lib/site-packages/에 설치
       └─> 시스템에 영향 없음

4. 비활성화
   deactivate
   └─> PATH 원복
       └─> 시스템 Python으로 복귀

설치 및 기본 사용법

venv 확인

venv는 Python 3.3+ 에 기본 포함되어 있습니다:


# Python 버전 확인
python3 --version
# Python 3.11.0
 
# venv 모듈 확인
python3 -m venv --help
# usage: venv [-h] ...

가상 환경 생성

기본 생성


# 현재 디렉토리에 'venv' 환경 생성
python3 -m venv venv
 
# 다른 이름으로 생성
python3 -m venv .venv      # 숨김 디렉토리
python3 -m venv myenv      # 커스텀 이름
python3 -m venv env-3.11   # 버전 명시

옵션 활용


# 시스템 패키지 접근 허용
python3 -m venv venv --system-site-packages
 
# pip 없이 생성 (수동 설치용)
python3 -m venv venv --without-pip
 
# 기존 환경 덮어쓰기
python3 -m venv venv --clear
 
# 심볼릭 링크 대신 복사
python3 -m venv venv --copies

가상 환경 활성화

Linux / macOS


# bash/zsh
source venv/bin/activate
 
# 또는 dot 명령어
. venv/bin/activate
 
# fish shell
source venv/bin/activate.fish
 
# csh/tcsh
source venv/bin/activate.csh

활성화 후 프롬프트 변경:


(venv) user@host:~/myproject$

Windows


# PowerShell
.\venv\Scripts\Activate.ps1
 
# 실행 정책 오류 시
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
.\venv\Scripts\Activate.ps1
 
# Command Prompt
venv\Scripts\activate.bat

가상 환경 사용


# 1. 환경 활성화
source venv/bin/activate
 
# 2. Python 및 pip 버전 확인
(venv) $ python --version
(venv) $ pip --version
 
# 3. 패키지 설치
(venv) $ pip install requests
(venv) $ pip install pandas numpy
 
# 4. 설치된 패키지 확인
(venv) $ pip list
 
# 5. 작업 완료 후 비활성화
(venv) $ deactivate
$  # 프롬프트에서 (venv) 사라짐

가상 환경 비활성화


# 모든 플랫폼에서 동일
deactivate

주요 사용 사례

사례 1: 새 프로젝트 시작


# 1. 프로젝트 디렉토리 생성
mkdir awesome-project
cd awesome-project
 
# 2. 가상 환경 생성
python3 -m venv venv
 
# 3. 활성화
source venv/bin/activate
 
# 4. 필요한 패키지 설치
pip install flask flask-sqlalchemy
 
# 5. requirements.txt 생성
pip freeze > requirements.txt
 
# 6. Git 저장소 초기화
git init
echo "venv/" >> .gitignore
git add .
git commit -m "Initial commit"

사례 2: 기존 프로젝트 복제


# 1. 저장소 클론
git clone https://github.com/user/project.git
cd project
 
# 2. 가상 환경 생성
python3 -m venv venv
 
# 3. 활성화
source venv/bin/activate
 
# 4. 의존성 설치
pip install -r requirements.txt
 
# 5. 애플리케이션 실행
python app.py

사례 3: 여러 Python 버전 관리


# Python 3.9 환경
python3.9 -m venv venv39
source venv39/bin/activate
pip install django==3.2
 
# Python 3.11 환경 (별도 터미널)
python3.11 -m venv venv311
source venv311/bin/activate
pip install django==4.2
 
# 각 환경에서 독립적으로 테스트 가능

사례 4: 개발/프로덕션 분리


# 개발 환경
python3 -m venv venv-dev
source venv-dev/bin/activate
pip install -r requirements-dev.txt  # pytest, black, mypy 포함
 
# 프로덕션 환경
python3 -m venv venv-prod
source venv-prod/bin/activate
pip install -r requirements.txt      # 최소 의존성만

디렉토리 구조 상세

venv 디렉토리 내부

Linux/macOS 구조


venv/
├── bin/
│   ├── activate              # bash/zsh 활성화 스크립트
│   ├── activate.csh          # csh 활성화 스크립트
│   ├── activate.fish         # fish 활성화 스크립트
│   ├── pip                   # pip 실행 파일
│   ├── pip3                  # pip3 심볼릭 링크
│   ├── python                # Python 심볼릭 링크
│   └── python3               # Python3 심볼릭 링크
├── include/
│   └── python3.11/           # C 헤더 파일
├── lib/
│   └── python3.11/
│       └── site-packages/    # 패키지 설치 위치
│           ├── pip/
│           ├── setuptools/
│           └── [설치한 패키지들]
└── pyvenv.cfg                # 환경 설정

Windows 구조


venv/
├── Scripts/
│   ├── activate.bat          # CMD 활성화 스크립트
│   ├── Activate.ps1          # PowerShell 활성화 스크립트
│   ├── deactivate.bat        # 비활성화 스크립트
│   ├── pip.exe               # pip 실행 파일
│   ├── python.exe            # Python 실행 파일
│   └── pythonw.exe           # GUI Python 실행 파일
├── Include/                  # C 헤더 파일
├── Lib/
│   └── site-packages/        # 패키지 설치 위치
└── pyvenv.cfg                # 환경 설정

pyvenv.cfg 파일


# venv/pyvenv.cfg 내용
home = /usr/bin
include-system-site-packages = false
version = 3.11.0
executable = /usr/bin/python3.11
command = /usr/bin/python3.11 -m venv /home/user/project/venv

주요 설정:

home: 베이스 Python 위치
include-system-site-packages: 시스템 패키지 접근 여부
version: Python 버전
executable: 실제 Python 인터프리터 경로

패키지 관리

requirements.txt 작성

기본 패키지 목록 생성


# 현재 환경의 모든 패키지 저장
pip freeze > requirements.txt

requirements.txt 예시


# requirements.txt
Django==4.2.0
djangorestframework==3.14.0
celery==5.3.0
redis==4.5.5
psycopg2-binary==2.9.6
python-dotenv==1.0.0

주석과 구조화


# Core Framework
Django==4.2.0
djangorestframework==3.14.0

# Task Queue
celery==5.3.0
redis==4.5.5

# Database
psycopg2-binary==2.9.6
sqlalchemy==2.0.15

# Utilities
python-dotenv==1.0.0
requests>=2.28.0,<3.0.0

의존성 설치


# requirements.txt로부터 설치
pip install -r requirements.txt
 
# 특정 버전 설치
pip install django==4.2.0
 
# 최신 버전 설치
pip install django
 
# 버전 범위 지정
pip install "django>=4.0,<5.0"
 
# 여러 패키지 동시 설치
pip install django flask fastapi

패키지 업데이트


# 단일 패키지 업데이트
pip install --upgrade django
 
# 모든 패키지 업데이트 (주의!)
pip list --outdated
pip install --upgrade package1 package2...
 
# requirements.txt 업데이트
pip freeze > requirements.txt

패키지 제거


# 단일 패키지 제거
pip uninstall django
 
# 여러 패키지 제거
pip uninstall package1 package2 package3
 
# requirements.txt의 모든 패키지 제거
pip uninstall -r requirements.txt -y

개발/프로덕션 의존성 분리


# requirements/ 디렉토리 구조
requirements/
├── base.txt           # 공통 의존성
├── development.txt    # 개발 의존성
└── production.txt     # 프로덕션 의존성

base.txt


# requirements/base.txt
Django==4.2.0
djangorestframework==3.14.0
celery==5.3.0

development.txt


# requirements/development.txt
-r base.txt

# Testing
pytest==7.3.1
pytest-django==4.5.2
pytest-cov==4.1.0

# Code Quality
black==23.3.0
flake8==6.0.0
mypy==1.3.0

# Debugging
django-debug-toolbar==4.1.0
ipython==8.14.0

production.txt


# requirements/production.txt
-r base.txt

# Production server
gunicorn==20.1.0
gevent==23.5.1

# Monitoring
sentry-sdk==1.25.1

사용


# 개발 환경
pip install -r requirements/development.txt
 
# 프로덕션 환경
pip install -r requirements/production.txt

실전 워크플로우

Django 프로젝트 시작


# 1. 프로젝트 디렉토리 생성
mkdir mysite
cd mysite
 
# 2. 가상 환경 생성
python3 -m venv venv
 
# 3. 활성화
source venv/bin/activate
 
# 4. Django 설치
pip install django
 
# 5. 프로젝트 생성
django-admin startproject config .
 
# 6. 추가 패키지 설치
pip install djangorestframework
pip install django-cors-headers
pip install python-dotenv
 
# 7. requirements.txt 생성
pip freeze > requirements.txt
 
# 8. .gitignore 설정
cat > .gitignore << 'EOF'
venv/
*.pyc
__pycache__/
db.sqlite3
.env
EOF
 
# 9. Git 초기화
git init
git add .
git commit -m "Initial Django project"

Flask API 프로젝트


# 1. 프로젝트 구조 생성
mkdir flask-api
cd flask-api
 
# 2. 가상 환경 생성 및 활성화
python3 -m venv venv
source venv/bin/activate
 
# 3. Flask 및 확장 설치
pip install flask
pip install flask-sqlalchemy
pip install flask-migrate
pip install flask-cors
pip install python-dotenv
 
# 4. 개발 도구 설치
pip install pytest
pip install black
pip install flake8
 
# 5. requirements 분리
mkdir requirements
pip freeze | grep -E "^(flask|python-dotenv)" > requirements/base.txt
pip freeze | grep -E "^(pytest|black|flake8)" > requirements/development.txt
 
# 6. 앱 구조 생성
mkdir -p app/{models,routes,services}
touch app/__init__.py
touch app/models/__init__.py
touch app/routes/__init__.py
touch app/services/__init__.py

데이터 과학 프로젝트


# 1. 프로젝트 생성
mkdir data-analysis
cd data-analysis
 
# 2. 가상 환경 생성
python3 -m venv venv
source venv/bin/activate
 
# 3. 데이터 과학 패키지 설치
pip install numpy
pip install pandas
pip install matplotlib
pip install seaborn
pip install scikit-learn
pip install jupyter
 
# 4. Jupyter 노트북 시작
jupyter notebook
 
# 5. requirements.txt 생성
pip freeze > requirements.txt

고급 기능

1. 시스템 패키지 접근


# 시스템 site-packages 접근 허용
python3 -m venv venv --system-site-packages
 
# 확인
source venv/bin/activate
python -c "import sys; print(sys.path)"
# 시스템 패키지 경로도 포함됨

사용 사례:

시스템에 이미 설치된 대용량 패키지 (NumPy, SciPy) 재사용
시스템 라이브러리와 연동 필요 시

주의사항:


# 시스템 패키지는 pip list에 표시되지 않음
pip list  # 가상 환경 패키지만 표시
 
# 전체 패키지 확인
pip list --user  # 시스템 패키지 포함

2. 가상 환경 복제


# 방법 1: requirements.txt 사용
source old-venv/bin/activate
pip freeze > requirements.txt
deactivate
 
python3 -m venv new-venv
source new-venv/bin/activate
pip install -r requirements.txt
 
# 방법 2: pip 직접 사용 (주의!)
cp -r old-venv new-venv
# ❌ 추천하지 않음 - 경로 문제 발생 가능

3. 가상 환경 이동


# ❌ 가상 환경은 이동 불가
mv venv ../new-location/venv
# 활성화 스크립트의 절대 경로가 깨짐
 
# ✅ 올바른 방법: 재생성
source venv/bin/activate
pip freeze > requirements.txt
deactivate
 
cd ../new-location
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

4. 다중 가상 환경 관리


# 프로젝트 구조
myproject/
├── venv-py39/        # Python 3.9 환경
├── venv-py311/       # Python 3.11 환경
├── venv-minimal/     # 최소 의존성
└── venv-full/        # 전체 의존성
 
# 환경 전환
source venv-py39/bin/activate   # Python 3.9로 테스트
deactivate
source venv-py311/bin/activate  # Python 3.11로 테스트

5. 환경 변수 관리


# activate 스크립트 수정 (활성화 시 자동 설정)
# venv/bin/activate 끝에 추가:
 
cat >> venv/bin/activate << 'EOF'
 
# 프로젝트별 환경 변수
export DATABASE_URL="postgresql://localhost/mydb"
export SECRET_KEY="dev-secret-key"
export DEBUG="True"
EOF
 
# 비활성화 시 제거
# deactivate 함수에 추가:
unset DATABASE_URL
unset SECRET_KEY
unset DEBUG

더 나은 방법: python-dotenv 사용


pip install python-dotenv
 
# .env 파일 생성
cat > .env << 'EOF'
DATABASE_URL=postgresql://localhost/mydb
SECRET_KEY=dev-secret-key
DEBUG=True
EOF
 
# .gitignore에 추가
echo ".env" >> .gitignore


# app.py
from dotenv import load_dotenv
import os
 
load_dotenv()  # .env 파일 로드
 
DATABASE_URL = os.getenv('DATABASE_URL')
SECRET_KEY = os.getenv('SECRET_KEY')

IDE 통합

VS Code 설정

방법 1: 자동 인식


# 가상 환경 생성
python3 -m venv venv
 
# VS Code 열기
code .
 
# Command Palette (Ctrl+Shift+P)
# > Python: Select Interpreter
# venv/bin/python 선택

방법 2: settings.json 설정


{
  "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "python.venvPath": "${workspaceFolder}"
}

통합 터미널 자동 활성화


{
  "terminal.integrated.env.linux": {
    "VIRTUAL_ENV": "${workspaceFolder}/venv"
  },
  "python.terminal.activateEnvInCurrentTerminal": true
}

PyCharm 설정


1. File > Settings > Project > Python Interpreter
2. Add Interpreter > Virtualenv Environment
3. Environment: Existing
4. Interpreter: /path/to/project/venv/bin/python
5. OK

Jupyter Notebook 통합


# 1. 가상 환경 활성화
source venv/bin/activate
 
# 2. ipykernel 설치
pip install ipykernel
 
# 3. 가상 환경을 Jupyter 커널로 등록
python -m ipykernel install --user --name=myproject --display-name="Python (myproject)"
 
# 4. Jupyter 실행
jupyter notebook
 
# 5. Notebook에서 커널 선택
# Kernel > Change kernel > Python (myproject)

문제 해결

문제 1: “python: command not found”

원인: python3가 설치되지 않았거나 PATH에 없음

해결:


# macOS
brew install python3
 
# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-venv
 
# CentOS/RHEL
sudo yum install python3
 
# 확인
python3 --version

문제 2: venv 활성화 실패 (Windows PowerShell)

증상:


.\venv\Scripts\Activate.ps1
# 오류: 이 시스템에서 스크립트를 실행할 수 없으므로...

원인: PowerShell 실행 정책 제한

해결:


# 현재 정책 확인
Get-ExecutionPolicy
 
# 정책 변경 (현재 사용자만)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
# 다시 활성화 시도
.\venv\Scripts\Activate.ps1

문제 3: pip 명령어 실패

증상:


(venv) $ pip install requests
# ERROR: Could not install packages due to an OSError

원인 1: pip 업데이트 필요


python -m pip install --upgrade pip

원인 2: 권한 문제


# ❌ sudo 사용하지 말 것
sudo pip install requests  # 시스템에 설치됨
 
# ✅ 가상 환경 확인
which pip  # /path/to/venv/bin/pip 이어야 함

문제 4: 가상 환경이 깨짐

증상:


source venv/bin/activate
# bash: venv/bin/activate: No such file or directory

해결:


# 1. 의존성 백업
pip freeze > requirements-backup.txt
 
# 2. 가상 환경 삭제
rm -rf venv
 
# 3. 재생성
python3 -m venv venv
 
# 4. 활성화
source venv/bin/activate
 
# 5. 의존성 복구
pip install -r requirements-backup.txt

문제 5: 잘못된 Python 버전

증상:


(venv) $ python --version
Python 2.7.18  # Python 3 기대했는데 2.7

해결:


# 가상 환경 재생성 시 명시적으로 지정
deactivate
rm -rf venv
python3.11 -m venv venv
source venv/bin/activate
python --version  # Python 3.11.x

문제 6: “externally-managed-environment” 오류 (Ubuntu 23.04+)

증상:


pip install requests
# error: externally-managed-environment

원인: 시스템 Python 보호

해결:


# ✅ 가상 환경 사용 (권장)
python3 -m venv venv
source venv/bin/activate
pip install requests
 
# 또는 --break-system-packages (비권장)
pip install requests --break-system-packages

베스트 프랙티스

1. 가상 환경 이름 컨벤션


# ✅ 권장
venv/          # 단순하고 명확
.venv/         # 숨김 디렉토리 (Git 무시 쉬움)
env/           # 짧음
 
# ❌ 비권장
virtualenv/    # 너무 김
myproject-venv/  # 중복 (디렉토리명이 이미 프로젝트명)

2. .gitignore 설정


# Python
*.py[cod]
*$py.class
__pycache__/

# 가상 환경
venv/
.venv/
env/
ENV/

# IDE
.vscode/
.idea/
*.swp
*.swo

# 환경 변수
.env
.env.local

# 데이터베이스
*.db
*.sqlite3

# OS
.DS_Store
Thumbs.db

3. README에 설정 방법 명시


# 프로젝트명
 
## 설치 방법
 
### 1. 저장소 클론
```bash
git clone https://github.com/user/project.git
cd project

2. 가상 환경 설정


python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

3. 의존성 설치


pip install -r requirements.txt

4. 환경 변수 설정


cp .env.example .env
# .env 파일을 편집하여 설정

5. 실행


python manage.py runserver



### 4. 프로젝트 구조 예시

myproject/ ├── venv/ # 가상 환경 (Git 무시) ├── src/ # 소스 코드 │ ├── init.py │ ├── main.py │ └── utils.py ├── tests/ # 테스트 │ ├── init.py │ └── test_main.py ├── requirements/ # 의존성 관리 │ ├── base.txt │ ├── development.txt │ └── production.txt ├── .env.example # 환경 변수 템플릿 ├── .gitignore ├── README.md └── setup.py



### 5. 가상 환경 활성화 자동화

**bash 사용자**

```bash
# ~/.bashrc 또는 ~/.bash_profile에 추가
function activate_venv() {
    if [ -f "venv/bin/activate" ]; then
        source venv/bin/activate
        echo "✓ 가상 환경 활성화됨"
    elif [ -f ".venv/bin/activate" ]; then
        source .venv/bin/activate
        echo "✓ 가상 환경 활성화됨"
    else
        echo "✗ 가상 환경을 찾을 수 없습니다"
    fi
}

# 사용: 프로젝트 디렉토리에서
activate_venv

zsh 사용자 (자동 활성화)


# ~/.zshrc에 추가
function auto_activate_venv() {
    if [[ -f venv/bin/activate ]]; then
        source venv/bin/activate
    elif [[ -f .venv/bin/activate ]]; then
        source .venv/bin/activate
    fi
}
 
# 디렉토리 변경 시 자동 실행
chpwd_functions=(${chpwd_functions[@]} "auto_activate_venv")

6. 팀 협업 가이드라인

의존성 관리 규칙:


# 새 패키지 추가 후
pip freeze > requirements.txt
git add requirements.txt
git commit -m "Add package-name dependency"
 
# 팀원이 pull 후
git pull
pip install -r requirements.txt

커밋 메시지 컨벤션:


deps: Add django-cors-headers for CORS support
deps: Update django to 4.2.0
deps: Remove unused package-name

venv vs 다른 도구 비교

venv vs virtualenv

특징	venv	virtualenv
Python 버전	3.3+ 기본 포함	별도 설치 필요
속도	빠름	약간 느림
Python 2 지원	없음	있음 (레거시)
기능	기본적	더 많은 옵션
추천 대상	대부분의 프로젝트	Python 2 필요 시

venv vs conda

특징	venv	conda
패키지 소스	PyPI	Anaconda + PyPI
시스템 라이브러리	Python만	Python + C/C++
디스크 사용량	적음 (~50MB)	많음 (~500MB)
설치 속도	빠름	느림
데이터 과학	수동 설정	최적화됨
추천 대상	웹 개발, API	데이터 과학, ML

venv vs Docker

특징	venv	Docker
격리 수준	Python 패키지	전체 시스템
오버헤드	최소	중간
이식성	OS 의존적	완전 이식 가능
학습 곡선	낮음	높음
추천 대상	개발 환경	배포, 마이크로서비스

venv vs Poetry

특징	venv	Poetry
의존성 관리	requirements.txt	pyproject.toml
잠금 파일	없음	poetry.lock
빌드 도구	없음	포함
복잡도	낮음	높음
추천 대상	간단한 프로젝트	패키지 개발, 복잡한 의존성

실무 시나리오

시나리오 1: 레거시 프로젝트 유지보수


# 문제: Python 2.7 프로젝트 유지 필요
# 해결: pyenv + virtualenv 사용
 
# pyenv 설치 (macOS)
brew install pyenv
 
# Python 2.7 설치
pyenv install 2.7.18
 
# 가상 환경 생성
pyenv virtualenv 2.7.18 legacy-project
 
# 활성화
pyenv activate legacy-project
 
# 의존성 설치
pip install -r requirements.txt

시나리오 2: 다중 서비스 모노레포


# 프로젝트 구조
monorepo/
├── service-a/
│   ├── venv/
│   └── requirements.txt
├── service-b/
│   ├── venv/
│   └── requirements.txt
└── shared/
    └── common-lib/
 
# 각 서비스 독립 환경
cd service-a
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -e ../shared/common-lib  # 공유 라이브러리 editable 설치

시나리오 3: CI/CD 파이프라인

GitHub Actions 예시:


name: Python Tests
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
 
    strategy:
      matrix:
        python-version: [3.9, 3.10, 3.11]
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up Python ${{ matrix.python-version }}
        uses: actions/setup-python@v4
        with:
          python-version: ${{ matrix.python-version }}
 
      - name: Create venv and install dependencies
        run: |
          python -m venv venv
          source venv/bin/activate
          pip install --upgrade pip
          pip install -r requirements/development.txt
 
      - name: Run tests
        run: |
          source venv/bin/activate
          pytest tests/ --cov=src --cov-report=xml
 
      - name: Upload coverage
        uses: codecov/codecov-action@v3

시나리오 4: AWS Lambda 배포


# 1. 로컬 개발 환경
python3 -m venv venv
source venv/bin/activate
pip install boto3 requests
 
# 2. Lambda 패키지 생성
mkdir lambda-package
pip install -r requirements.txt -t lambda-package/
cp lambda_function.py lambda-package/
 
# 3. ZIP 생성
cd lambda-package
zip -r ../lambda-function.zip .
 
# 4. AWS Lambda 업로드
aws lambda update-function-code \
    --function-name my-function \
    --zip-file fileb://../lambda-function.zip

다음 단계

추가 학습 자료

Python 공식 문서: https://docs.python.org/3/library/venv.html
PEP 405: https://peps.python.org/pep-0405/ (venv 제안)
Real Python 튜토리얼: https://realpython.com/python-virtual-environments-a-primer/

고급 주제

pyenv: 여러 Python 버전 관리
Poetry: 현대적 패키지 및 의존성 관리
Docker: 컨테이너 기반 격리
tox: 다중 환경 테스트 자동화

요약

venv는 Python 표준 라이브러리에 포함된 가상 환경 관리 도구로, 프로젝트별로 독립된 Python 환경을 제공합니다.

핵심 개념:

🔒 패키지 격리: 프로젝트별 독립적인 패키지 관리
🛡️ 시스템 보호: 전역 Python 환경 오염 방지
🔄 재현성: requirements.txt로 동일 환경 재현
📦 표준 도구: Python 3.3+ 기본 포함

기본 사용법:


# 생성
python3 -m venv venv
 
# 활성화
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows
 
# 패키지 설치
pip install requests
 
# 비활성화
deactivate

언제 사용하나요?

모든 Python 프로젝트 (필수!)
의존성 충돌 방지
팀 협업에서 환경 통일
여러 Python 버전 테스트

venv를 활용하여 깔끔하고 관리하기 쉬운 Python 프로젝트를 만들어 보세요!

2025•developjik

All content is licensed under CC BY-NC-SA 4.0 unless otherwise noted.

개요

배경