Virtual Environment Management

가상환경이 필요한 프로젝트에서 환경을 체크하고 생성하는 스킬입니다.

When This Skill Activates

다음 파일 발견 시 가상환경 필요 여부 체크:

파일	프로젝트 유형	가상환경
`requirements.txt`	Python	venv/virtualenv
`pyproject.toml`	Python (Poetry/PDM)	Poetry/PDM 내장
`Pipfile`	Python (Pipenv)	Pipenv 내장
`setup.py`	Python 패키지	venv
`package.json`	Node.js	node_modules (자동)
`Gemfile`	Ruby	bundler
`go.mod`	Go	모듈 시스템 (자동)

Detection Workflow

1. 프로젝트 유형 감지

bash

# 프로젝트 루트에서 실행
ls -la | grep -E "requirements|pyproject|Pipfile|package\.json|Gemfile|go\.mod"

2. 가상환경 존재 확인

bash

# Python venv 확인
ls -la | grep -E "^d.*(venv|\.venv|env|\.env)$"

# Python - 활성화 여부
echo $VIRTUAL_ENV

# Node - node_modules 확인
ls -d node_modules 2>/dev/null

Python Projects

venv (표준 라이브러리)

bash

# 가상환경 생성
python -m venv .venv

# 활성화 (macOS/Linux)
source .venv/bin/activate

# 활성화 (Windows)
.venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

# 비활성화
deactivate

Poetry (권장)

bash

# Poetry 설치 확인
poetry --version

# 가상환경 자동 생성 + 의존성 설치
poetry install

# 가상환경 내에서 실행
poetry run python script.py

# 쉘 진입
poetry shell

Pipenv

bash

# 가상환경 생성 + 의존성 설치
pipenv install

# 가상환경 쉘 진입
pipenv shell

# 가상환경 내에서 실행
pipenv run python script.py

Conda

bash

# 환경 생성
conda create -n myenv python=3.11

# 활성화
conda activate myenv

# 의존성 설치
conda install --file requirements.txt
# 또는
pip install -r requirements.txt

Node.js Projects

bash

# 의존성 설치 (node_modules 자동 생성)
npm install
# 또는
yarn install
# 또는
pnpm install

# 확인
ls node_modules

Workflow: 프로젝트 시작 시

Python 프로젝트

code

1. 프로젝트 유형 확인
   - pyproject.toml → Poetry/PDM
   - Pipfile → Pipenv
   - requirements.txt → venv

2. 가상환경 존재 확인
   ls -la | grep -E "venv|\.venv"

3. 없으면 생성
   python -m venv .venv

4. 활성화 + 의존성 설치
   source .venv/bin/activate
   pip install -r requirements.txt

Node.js 프로젝트

code

1. package.json 확인
   cat package.json | head -20

2. node_modules 확인
   ls node_modules 2>/dev/null

3. 없으면 설치
   npm install

Naming Conventions

이름	권장	비고
`.venv`	✅ 권장	숨김 폴더, 일반적
`venv`	✅ 허용	명시적
`.env`	⚠️ 주의	환경변수 파일과 혼동
`env`	⚠️ 주의	너무 일반적

.gitignore 설정

gitignore

# Python virtual environments
.venv/
venv/
env/
.env/

# Node
node_modules/

# Python cache
__pycache__/
*.pyc
.pytest_cache/

# IDE
.idea/
.vscode/

Quick Reference

Python 프로젝트 시작

bash

# 1. 가상환경 체크 및 생성
[ -d ".venv" ] || python -m venv .venv

# 2. 활성화
source .venv/bin/activate

# 3. 의존성 설치
pip install -r requirements.txt

Node.js 프로젝트 시작

bash

# 1. node_modules 체크 및 설치
[ -d "node_modules" ] || npm install

Troubleshooting

문제	해결
`python: command not found`	Python 설치 또는 PATH 확인
`pip: command not found`	가상환경 활성화 확인
Permission denied	`sudo` 사용 금지, venv 재생성
패키지 충돌	가상환경 삭제 후 재생성
node_modules 오류	`rm -rf node_modules && npm install`

Checklist

프로젝트 시작 전:

• 프로젝트 유형 확인 (Python/Node/etc.)
• 가상환경 존재 여부 확인
• 없으면 생성
• 활성화 (Python)
• 의존성 설치
• .gitignore에 가상환경 폴더 포함 확인