目次
Pythonプロジェクトで「動かない」トラブルの多くは、環境の汚染や依存関係の衝突が原因だ。本記事では、仮想環境の必要性と、venv・uv・pyenvの使い分けを整理する。
なぜ仮想環境が必要か
Pythonのパッケージはデフォルトでシステム全体にインストールされる。複数のプロジェクトが同じパッケージの異なるバージョンを要求すると衝突する。
プロジェクトA: requests==2.28.0 が必要
プロジェクトB: requests==2.31.0 が必要
→ 両立不可能(システムにはどちらか一方しか入らない)
仮想環境を使うとプロジェクトごとに独立したパッケージ空間を持てる。
venv——標準ライブラリ
Python 3.3以降に組み込まれた公式の仮想環境ツール。追加インストール不要。
# 仮想環境を作成
python -m venv .venv
# 有効化
source .venv/bin/activate # Linux/Mac
.venv\Scripts\activate # Windows
# パッケージをインストール
pip install requests numpy
# 依存関係を保存
pip freeze > requirements.txt
# 別の環境で再現
pip install -r requirements.txt
# 無効化
deactivate
適している場面: シンプルなプロジェクト、CI/CD環境、追加ツール不要な場合
欠点: Pythonバージョン自体の管理はできない。インストールが pip ベースで遅い。
uv——次世代の高速パッケージ管理
Rustで書かれた高速なPythonパッケージマネージャー。pipより10〜100倍速い。
# インストール(macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# プロジェクト初期化
uv init my-project
cd my-project
# 仮想環境作成 + パッケージ追加
uv add requests numpy
# 仮想環境を使ってコマンド実行
uv run python script.py
# 依存関係はpyproject.tomlで管理される
pyproject.toml が自動生成される:
[project]
name = "my-project"
version = "0.1.0"
dependencies = [
"requests>=2.31.0",
"numpy>=1.26.0",
]
適している場面: 新規プロジェクト、速度重視、モダンなプロジェクト構成
強み: ロックファイル(uv.lock)による完全な再現性、仮想環境の自動管理
pyenv——Pythonバージョン管理
複数のPythonバージョンをシステムに共存させるツール。venvやuvと組み合わせて使う。
# インストール(Linux/Mac)
curl https://pyenv.run | bash
# 利用可能なバージョン確認
pyenv install --list | grep "3.1"
# バージョンをインストール
pyenv install 3.11.9
pyenv install 3.12.3
# グローバルデフォルトを設定
pyenv global 3.12.3
# プロジェクトローカルのバージョンを設定(.python-versionファイルを生成)
cd my-project
pyenv local 3.11.9
python --version # 3.11.9
# インストール済みバージョン一覧
pyenv versions
適している場面: 古いバージョンが必要なプロジェクト、複数バージョンの並行テスト
ツールの使い分けまとめ
| 状況 | 推奨ツール |
|---|---|
| 手軽に始めたい | venv + pip |
| 速さと再現性を重視 | uv |
| Python バージョンを切り替えたい | pyenv + venv または pyenv + uv |
| チーム開発・CI/CD | uv(ロックファイルで完全再現) |
AI開発での推奨構成
機械学習やAI開発では依存関係が複雑になりやすい。推奨構成:
# 1. pyenv で Python バージョンを固定
pyenv install 3.11.9
pyenv local 3.11.9
# 2. uv でプロジェクト管理
uv init
uv add torch torchvision numpy pandas jupyter
# 3. 実行
uv run jupyter notebook
uv.lock をGit管理に含めることで、チーム全員が同じ環境を再現できる。
まとめ
- venv: 標準ツール、シンプルな使い方に最適
- uv: 高速・モダン、新規プロジェクトの第一選択肢
- pyenv: Pythonバージョン自体を管理したいときに使う
- 仮想環境の作成は「プロジェクトを始めたら即座に」が鉄則
requirements.txtまたはuv.lockを必ず Git に含める
免責事項 — 掲載情報は執筆時点のものです。料金・機能は変更される場合があります。最新情報は各公式サイトをご確認ください。