Pythonのvenv運用のベストプラクティス

※Claude Sonnet 4.6回答

基本構成

# プロジェクトごとに作成するのが基本
my_project/
├── .venv/          # venv本体（プロジェクト直下に置く）
├── requirements.txt
├── requirements-dev.txt
└── src/

1. 作成・有効化

# 作成（Python 3.3+ 標準搭載）
python -m venv .venv

# 有効化
source .venv/bin/activate        # macOS / Linux
.venv\Scripts\activate           # Windows (cmd)
.venv\Scripts\Activate.ps1       # Windows (PowerShell)

# 無効化
deactivate

命名は .venv が事実上の標準（.gitignore テンプレートがデフォルト対応）

2. `.gitignore` に必ず追加

.venv/
__pycache__/
*.pyc
*.pyo

3. 依存パッケージの管理

運用・本番用と開発用を分ける

# requirements.txt（本番）
flask==3.1.0
requests==2.32.3

# requirements-dev.txt（開発・テスト用）
-r requirements.txt
pytest==8.3.5
black==25.1.0
ruff==0.9.0

# 本番インストール
pip install -r requirements.txt

# 開発環境インストール
pip install -r requirements-dev.txt

バージョンを固定してロックする

# 現在の環境を丸ごと書き出し（ロックファイル相当）
pip freeze > requirements.lock

# 再現インストール
pip install -r requirements.lock

4. pip を最初に必ずアップグレード

python -m pip install --upgrade pip

venv 作成直後の pip は古いことが多く、依存解決エラーの原因になる。

5. Python バージョンを明示する

# バージョンを指定して作成
python3.12 -m venv .venv

# .python-version に記録（pyenvと連携）
echo "3.12.3" > .python-version

6. ワンライナーでセットアップを自動化

Makefile に書いておくと再現が楽：

.PHONY: setup update clean

setup:
    python -m venv .venv
    .venv/bin/pip install --upgrade pip
    .venv/bin/pip install -r requirements-dev.txt

update:
    .venv/bin/pip install --upgrade -r requirements-dev.txt
    .venv/bin/pip freeze > requirements.lock

clean:
    rm -rf .venv __pycache__

make setup   # 初回セットアップ
make update  # パッケージ更新
make clean   # 環境リセット

7. VS Code との連携

.vscode/settings.json に記述しておくと自動認識：

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}

8. CI/CD（GitHub Actions）での扱い

- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: "3.12"

- name: Install dependencies
  run: |
    python -m venv .venv
    .venv/bin/pip install --upgrade pip
    .venv/bin/pip install -r requirements.lock

ツール選定の目安

規模・用途	推奨
スクリプト・小規模	venv + pip（標準、シンプル）
ライブラリ開発・配布	Poetry or Hatch（pyproject.toml統合）
データサイエンス	conda / miniforge（C拡張に強い）
複数Pythonバージョン管理	pyenv + venv
超高速インストール重視	uv（Rust製、pipの10〜100倍速）

よくあるミス

# ❌ venv を有効化せずに pip install してしまう
pip install flask   # システムPythonに入ってしまう

# ✅ 有効化を確認してから
which python        # .venv/bin/python になっていることを確認
pip install flask

# ❌ venv ごとコミットしてしまう
git add .venv       # バイナリ・パスがハードコードされており移植不可

# ✅ requirements.txt だけコミットして再現できるようにする

基本原則は「1プロジェクト = 1 .venv」「依存は requirements.txt で管理」「venv 本体は git に入れない」 の3点です。規模が大きくなったら Poetry や uv への移行を検討してください。