python-env

Python 環境

uv を使った高速な Python 環境管理。uv pip 互換レイヤーよりも、uv の プロジェクトワークフロー（uv add / uv sync / uv run）を優先してください。pyproject.toml とロックファイルを管理してくれるため、再現性が確保されます。

クイックコマンド

タスク	コマンド
プロジェクトを開始する	uv init <name>（アプリ） · uv init --package <name>（インストール可能、src/ レイアウト）
依存関係を追加する	uv add httpx
開発用の依存関係を追加する	uv add --dev pytest ruff
依存関係を削除する	uv remove httpx
ロックファイルから環境を同期する	uv sync
プロジェクト環境で実行する	uv run pytest
ロックファイルを更新する	uv lock
CLI ツールをインストールする	uv tool install ruff · 1 回だけ実行する場合：uvx ruff
Python をインストールする	uv python install 3.12

プロジェクトを開始する

# Application (flat layout, no package build)
uv init myapp

# Installable package (src/ layout — separate tests/ that import by name)
uv init --package wordtools
# → src/wordtools/__init__.py, pyproject.toml with build-system

uv init は pyproject.toml を作成し、Python のバージョンを固定して、uv add / uv sync を使えるようにプロジェクトを準備します。テストスイートがあるプロジェクトや、配布する予定のプロジェクトには、--package（src）レイアウトがおすすめです。

依存関係を管理する

# Add runtime deps (writes to [project.dependencies] + updates the lockfile)
uv add "httpx>=0.25" pydantic

# Add dev-only deps (writes to the dev dependency-group)
uv add --dev pytest ruff mypy

# Add with extras
uv add "fastapi[standard]"

# Remove
uv remove httpx

# Install everything from pyproject + uv.lock into .venv (reproducible)
uv sync

# Refresh the lockfile (e.g. after manual pyproject edits)
uv lock

uv は .venv を自動的に作成・管理するため、環境を有効化する必要はほとんどありません。コマンドの前に uv run を付けるだけです。

コードを実行する

uv run python script.py     # run a script in the project env
uv run pytest               # run a tool from the dev group
uv run -- ruff check .      # `--` ends uv flag parsing

uv プロジェクトでは、python / pytest / ruff をそのまま呼び出さないでください。別のインタープリターが選ばれる可能性があります。必ず uv run を使ってください。

CLI ツール（グローバル、プロジェクトの依存関係ではないもの）

uv tool install ruff        # persistent, isolated, on PATH
uv tool upgrade ruff
uvx ruff check .            # ephemeral one-shot run, nothing installed

開発者向け CLI（ruff、pre-commit、httpie）には uv tool / uvx を使ってください。uv add はコードからインポートするものにだけ使ってください。

Python のバージョン

uv python install 3.12      # download a managed interpreter
uv python list              # show available + installed
uv init --python 3.12 app   # pin a project to a version

現在の安定版は python.org で確認してください（2026-07 時点では 3.14 です。最近のリリースでは、オプトイン形式のフリースレッド化と JIT が追加されています）。新しいプロジェクトでは、3.11 以降を妥当な最低バージョンとするのがおすすめです（TaskGroup、Self、インタープリターの高速化）。

最小限の pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "httpx>=0.25",
    "pydantic>=2.0",
]

# Dev deps live here; `uv add --dev <pkg>` manages this group.
[dependency-groups]
dev = [
    "pytest>=8.0",
    "ruff>=0.4",
    "mypy>=1.10",
]

互換レイヤー（uv pip）— 最終手段

uv pip は、uv が管理していない環境（手動で作成した venv、レガシーな requirements.txt、uv をネイティブに使わない CI）向けに、pip のインターフェースを再現します。pyproject.toml やロックファイルは更新されません。プロジェクトを自分で管理できる場合は、uv add / uv sync を優先してください。

uv venv                              # bare venv (no project)
uv pip install -r requirements.txt   # legacy requirements file
uv pip install -e .                  # editable install into an unmanaged venv
uv pip compile requirements.in -o requirements.txt   # pin a requirements.txt

トラブルシューティング

問題	解決方法
"No Python found"	uv python install 3.12
プロジェクトの Python を固定する	uv init --python 3.12 または requires-python を編集する
ロック／依存関係解決の競合	uv lock --resolution=lowest-direct で調査し、その後、バージョン範囲の制約を緩める
pull 後に環境が古い	uv sync
キャッシュの問題	uv cache clean

使用する場面

• 常に pip より uv を使ってください — 10～100 倍高速です
• プロジェクトの依存関係には uv add / uv remove / uv sync を使ってください（uv pip install ではありません）
• プロジェクト環境内で何かを実行するときは uv run を使ってください
• 単体で使う開発者向け CLI には uv tool install / uvx を使ってください
• uv pip は uv が管理していない環境でのみ使ってください

追加リソース

詳しいパターンについては、以下を参照してください。

• ./references/pyproject-patterns.md - pyproject.toml の詳細な例、ツール設定
• ./references/dependency-management.md - ロックファイル、ワークスペース、プライベートパッケージ
• ./references/publishing.md - PyPI への公開、バージョン管理、CI/CD

---

関連項目

これは前提条件のない基礎スキルです。

このスキルを基盤にする：

• python-typing-ops - プロジェクトの型ヒント
• python-pytest-ops - テストインフラストラクチャ
• python-fastapi-ops - Web API 開発