目次

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/CDuv(ロックファイルで完全再現)

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 に含める

免責事項 — 掲載情報は執筆時点のものです。料金・機能は変更される場合があります。最新情報は各公式サイトをご確認ください。