VENV

이 문서는 파이썬 가상환경 개념 노트와 작업 내용을 기록합니다.

---

.venv 는 파이썬의 가상환경(virtual environment)으로, 각 프로젝트별로 독립적인 패키지 설치 및 실행 환경을 제공합니다.

가상환경을 사용하면 다음과 같은 이점이 있습니다:

• 프로젝트 간 패키지 충돌 방지
• 동일한 의존성 버전 유지
• 개발 환경과 배포 환경 간 일관성 확보

관련 작업 PR

• 파이썬 오픈 소스 라이브러리 s2n PR
• 관련 작업 PR

---

표준 Python 버전 관리

1. Python 버전 명시 (.python-version)

팀 전체가 동일한 Python 버전을 사용하는 것이 중요합니다.
pyenv 를 사용하여 버전을 고정합니다.

.python-version 파일에 다음과 같이 명시합니다:

3.11.9

2. pyenv 설치 및 버전 활성화

# pyenv 설치 (macOS)
brew install pyenv

# Ubuntu 설치
# pyenv는 apt 패키지로 제공되지 않으므로 공식 설치 스크립트를 사용해야 합니다.
curl https://pyenv.run | bash

# Python 버전 설치 및 적용
pyenv install 3.11.9
pyenv local 3.11.9

협업 프로젝트에서 다루었던 내용이어서, 이 작업을 한 뒤 가이드를 작성했습니다.

파이썬 오픈 소스 라이브러리 s2n PR

문제: 파이썬 코드가 팀원들의 로컬 환경마다 에러를 일으키거나 일으키지 않음. 원인:

• 팀원들이 모두 동일한 파이썬 버전을 사용하지 않았음.
• @dataclass slot 파라미터를 3.11 이상 버전에서 사용할 수 있음. 해결: pyenv + direnv 및 requirements.txt와 activate 스크립트 작성

---

2) runtime.txt (외부 호스팅 환경용)

Heroku 등 일부 배포 환경에서는 Python 버전을 runtime.txt 파일로 명시한다고 합니다.

python-3.11.9

---

3. .venv 환경 일관성 유지하기

1) 가상환경 생성 규칙

모든 팀원이 동일한 방식으로 .venv 를 생성하도록 규정합니다.

가상환경 생성:

python -m venv .venv

활성화:

OS	명령어
macOS/Linux	source .venv/bin/activate
Windows	.venv\Scripts\activate

가상환경 디렉터리는 항상 프로젝트 루트에 위치시키는 것을 원칙으로 합니다.

---

2) .gitignore 설정

Git 저장소에는 .venv 디렉터리를 포함하지 않습니다.
처음이다 보니 저도 놓쳤던 것 같습니다.

.gitignore 예시:

# Python
__pycache__/
*.py[cod]
*.egg-info/

# Virtual environment
.venv/
.env/
venv/

---

3) 의존성 관리 파일

모든 팀원이 동일한 패키지 버전을 유지하기 위해 의존성 파일을 사용합니다.
특히 오픈 소스 PyPi 패키지를 만드는 작업이었기에, 일관된 환경 설정에 더 신경을 썼습니다.

(1) requirements.txt

pip freeze > requirements.txt

설치 시:

pip install -r requirements.txt

(2) pyproject.toml + Poetry

[tool.poetry]
name = "myproject"
version = "0.1.0"
description = "A PyPI-ready package"
authors = ["Team <team@example.com>"]

[tool.poetry.dependencies]
python = "^3.11"
requests = "^2.31.0"

---

4. 에디터 설정 공유

1) VSCode 설정 (.vscode/settings.json)

모든 팀원이 동일한 인터프리터 설정을 사용하도록 구성합니다. 관련 작업 PR

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.venvPath": "${workspaceFolder}/.venv",
  "python.linting.enabled": true,
  "python.linting.pylintEnabled": true,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  },
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false
}

VSCode는 .venv 를 자동 인식하지 못하는 경우가 있으므로 경로를 명시적으로 지정하는 것이 좋습니다.

---

2) PyCharm / IntelliJ 설정 (.idea/)

PyCharm은 .idea 디렉터리에 프로젝트 설정을 저장합니다.

misc.xml 예시:

<project version="4">
  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.11 (.venv)" project-jdk-type="Python SDK" />
</project>

.idea/.gitignore 예시:

# IntelliJ project settings
workspace.xml
tasks.xml
shelf/
dictionaries/

공통 설정은 공유하되, 개인 설정 파일(workspace.xml 등)은 저장소에 포함하지 않습니다.

---

5. 배포 전 환경 검증 절차

1. 의존성 동기화

   pip install -r requirements.txt

2. Python 버전 확인

   python --version

3. 테스트 실행

   pytest

4. PyPI 패키징 테스트

   python -m build
   twine check dist/*

---

6. 팀 협업용 초기화 스크립트

setup_env.sh 파일을 통해 모든 팀원이 동일한 방식으로 환경을 구축할 수 있습니다.

#!/bin/bash
set -e

echo "Setting up Python environment..."

# Python 버전 확인
PY_VERSION=$(python3 --version)
echo "Using $PY_VERSION"

# 가상환경 생성
python3 -m venv .venv
source .venv/bin/activate

# 패키지 설치
pip install --upgrade pip
pip install -r requirements.txt

echo "Virtual environment ready."

(이 과정이 팀원 모두에게 너무 번거롭고 귀찮을 것 같아, 비슷한 환경 구성 스크립트를 작성했었습니다.) 참고 PR

실행:

chmod +x setup_env.sh
./setup_env.sh

요약

항목	목적	구성 요소
Python 버전 고정	환경 일관성 유지	.python-version, pyenv
가상환경 관리	의존성 분리	.venv/, requirements.txt
코드 에디터 통합	개발 환경 통일	.vscode/settings.json, .idea/misc.xml
자동화 스크립트	환경 세팅 간소화	setup_env.sh

---

.venv, .vscode, .idea, .python-version 파일을 저장소에 포함시키면 팀 전체가 동일한 개발 환경에서 동일한 Python 버전으로 프로젝트를 관리할 수 있습니다.