python-package-management

クイックリファレンス

uv コマンド	用途
uv init my-project	新しいプロジェクトを作成
uv add <package>	依存関係を追加
uv add --dev <package>	開発用の依存関係を追加
uv sync	すべての依存関係をインストール
uv run <command>	仮想環境で実行
uv lock --upgrade	すべての依存関係を更新
uv python install 3.13	Python のバージョンをインストール

ツール	コマンド	速度
uv	uv add requests	10～100 倍高速
pip	pip install requests	基準

ruff コマンド	用途
ruff check .	コードをリント
ruff check --fix .	問題を自動修正
ruff format .	コードをフォーマット

プロジェクトの構成	推奨
src レイアウト	src/my_package/
テスト	tests/
設定	pyproject.toml

このスキルを使う場面

プロジェクトのセットアップと依存関係に使用します。

• 新しい Python プロジェクトを開始するとき
• 高速なパッケージ管理のために uv をセットアップするとき
• pyproject.toml を設定するとき
• ruff でリントをセットアップするとき
• PyPI にパッケージを公開するとき

関連するスキル：

• CI/CD については、python-github-actions を参照してください
• テストについては、python-testing を参照してください
• 型ヒントの設定については、python-type-hints を参照してください

---

Python パッケージ管理（2025）

概要

最新の Python パッケージ管理の中心となるのは、uv（高速な Rust ベースのツール）、pip、pyproject.toml です。このガイドでは、依存関係管理、仮想環境、プロジェクト設定のベストプラクティスを説明します。

uv - 最新のパッケージマネージャー

uv を使う理由

• pip より 10～100 倍高速（Rust で記述）
• pip、pip-tools、pipx、poetry、pyenv、virtualenv を置き換えます
• 仮想環境を自動で管理します
• 再現性を確保するためのロックファイルをサポートします
• venv の作成が約 200 倍高速です

インストール

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

# pip (works everywhere)
pip install uv

# Homebrew
brew install uv

クイックスタート

# Create new project
uv init my-project
cd my-project

# Add dependencies
uv add requests fastapi pydantic

# Add dev dependencies
uv add --dev pytest ruff mypy

# Sync environment (install all dependencies)
uv sync

# Run commands in the environment
uv run python main.py
uv run pytest

基本コマンド

# Package management
uv add <package>              # Add dependency
uv add <package>==1.0.0       # Specific version
uv add --dev <package>        # Dev dependency
uv remove <package>           # Remove dependency
uv sync                       # Sync environment with lockfile

# Virtual environments
uv venv                       # Create .venv
uv venv --python 3.12         # Specific Python version
uv venv my-env                # Named environment

# pip compatibility
uv pip install <package>      # Install (faster pip)
uv pip install -r requirements.txt
uv pip freeze > requirements.txt
uv pip compile pyproject.toml -o requirements.txt

# Python management
uv python install 3.13        # Install Python version
uv python list                # List installed versions
uv python pin 3.12            # Pin project Python version

# Running
uv run <command>              # Run in virtual env
uv run --with httpx python    # Run with temporary package

uv を使用した pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
description = "My Python project"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "[email protected]"}
]
dependencies = [
    "fastapi>=0.100.0",
    "pydantic>=2.0.0",
    "httpx>=0.25.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.1.0",
    "mypy>=1.8.0",
]

[project.scripts]
my-cli = "my_project.cli:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
dev-dependencies = [
    "pytest>=8.0.0",
    "ruff>=0.1.0",
    "mypy>=1.8.0",
]

uv.lock

# Lockfile is auto-generated and should be committed
# Contains exact versions for reproducibility

# Update all dependencies
uv lock --upgrade

# Update specific package
uv lock --upgrade-package requests

# Install from lockfile only
uv sync --frozen

プロジェクト構成

推奨：src レイアウト

my-project/
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── main.py
│       ├── models.py
│       └── utils/
│           ├── __init__.py
│           └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_main.py
│   └── test_models.py
├── docs/
│   └── index.md
├── pyproject.toml
├── uv.lock
├── README.md
├── LICENSE
└── .gitignore

src レイアウトを使う理由

1. インポートの混乱を防ぐ - プロジェクトのルートから誤ってインポートできません
2. インストールを必須にする - テストするにはパッケージをインストールする必要があります
3. 配布物をすっきりさせる - wheel にはパッケージのコードだけが含まれます
4. 意味上の明確さ - コード、テスト、ドキュメントを明確に分離します

フラットレイアウト（よりシンプルなプロジェクト向け）

my-project/
├── my_package/
│   ├── __init__.py
│   └── main.py
├── tests/
│   └── test_main.py
├── pyproject.toml
└── README.md

pyproject.toml 完全リファレンス

[project]
name = "my-project"
version = "1.0.0"
description = "A comprehensive Python project"
readme = "README.md"
requires-python = ">=3.11"
license = {text = "MIT"}
keywords = ["python", "example", "package"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Developers",
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
]
authors = [
    {name = "Your Name", email = "[email protected]"}
]
maintainers = [
    {name = "Maintainer", email = "[email protected]"}
]

dependencies = [
    "fastapi>=0.100.0",
    "pydantic>=2.0.0",
    "sqlalchemy>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "pytest-cov>=4.0.0",
    "ruff>=0.1.0",
    "mypy>=1.8.0",
    "pre-commit>=3.0.0",
]
docs = [
    "mkdocs>=1.5.0",
    "mkdocs-material>=9.0.0",
]
all = ["my-project[dev,docs]"]

[project.scripts]
my-cli = "my_package.cli:main"

[project.entry-points."my_package.plugins"]
plugin1 = "my_package.plugins:Plugin1"

[project.urls]
Homepage = "https://github.com/user/my-project"
Documentation = "https://my-project.readthedocs.io"
Repository = "https://github.com/user/my-project"
Changelog = "https://github.com/user/my-project/blob/main/CHANGELOG.md"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["src/my_package"]

# Ruff configuration
[tool.ruff]
target-version = "py311"
line-length = 88
src = ["src", "tests"]

[tool.ruff.lint]
select = [
    "E",     # pycodestyle errors
    "W",     # pycodestyle warnings
    "F",     # Pyflakes
    "I",     # isort
    "B",     # flake8-bugbear
    "C4",    # flake8-comprehensions
    "UP",    # pyupgrade
    "ARG",   # flake8-unused-arguments
    "SIM",   # flake8-simplify
]
ignore = [
    "E501",  # line too long (handled by formatter)
]

[tool.ruff.lint.isort]
known-first-party = ["my_package"]

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

# Mypy configuration
[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
warn_unused_ignores = true
disallow_untyped_defs = true
plugins = ["pydantic.mypy"]

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

# Pytest configuration
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_functions = ["test_*"]
addopts = [
    "-ra",
    "-q",
    "--strict-markers",
    "--cov=src/my_package",
    "--cov-report=term-missing",
]

# Coverage configuration
[tool.coverage.run]
branch = true
source = ["src/my_package"]
omit = ["*/tests/*", "*/__init__.py"]

[tool.coverage.report]
exclude_lines = [
    "pragma: no cover",
    "def __repr__",
    "raise NotImplementedError",
    "if TYPE_CHECKING:",
]

Ruff - リントとフォーマット

Ruff を使う理由

• Flake8 と Black を合わせたものより 10～100 倍高速
• リントとフォーマットの両方に使える単一のツール
• 800 以上の組み込みルール
• 自動修正機能
• Rust で記述（uv と同じく Astral による開発）

基本的な使い方

# Linting
ruff check .                   # Check for issues
ruff check --fix .             # Auto-fix issues
ruff check --watch .           # Watch mode

# Formatting
ruff format .                  # Format all files
ruff format --check .          # Check formatting

# Both
ruff check --fix . && ruff format .

設定

# pyproject.toml
[tool.ruff]
target-version = "py311"
line-length = 88
src = ["src", "tests"]

[tool.ruff.lint]
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # Pyflakes
    "I",      # isort
    "B",      # flake8-bugbear
    "C4",     # flake8-comprehensions
    "UP",     # pyupgrade
    "ARG",    # flake8-unused-arguments
    "SIM",    # flake8-simplify
    "TCH",    # flake8-type-checking
    "PTH",    # flake8-use-pathlib
    "ERA",    # eradicate (commented code)
    "PL",     # Pylint
    "PERF",   # Perflint
    "RUF",    # Ruff-specific rules
]
ignore = [
    "E501",   # line too long (handled by formatter)
    "PLR0913", # too many arguments
]

# Per-file ignores
[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101"]  # Allow assert in tests
"__init__.py" = ["F401"]    # Allow unused imports

[tool.ruff.lint.isort]
known-first-party = ["my_package"]
force-single-line = true

[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"

Pre-commit との統合

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.4.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.9.0
    hooks:
      - id: mypy
        additional_dependencies:
          - pydantic
          - types-requests

pip と requirements.txt

pip を使う場面

• 安定性が求められる本番環境
• レガシープロジェクト
• 複雑な依存関係のないシンプルなスクリプト

requirements.txt のベストプラクティス

# requirements.txt - Pinned versions for production
fastapi==0.109.0
pydantic==2.5.3
sqlalchemy==2.0.25
httpx==0.26.0

# requirements-dev.txt
-r requirements.txt
pytest==8.0.0
ruff==0.1.14
mypy==1.8.0

requirements.txt の生成

# From uv
uv pip compile pyproject.toml -o requirements.txt
uv pip compile pyproject.toml --extra dev -o requirements-dev.txt

# From pip-tools
pip-compile pyproject.toml -o requirements.txt
pip-compile pyproject.toml --extra dev -o requirements-dev.txt

# Freeze current environment (not recommended for reproducibility)
pip freeze > requirements.txt

仮想環境のベストプラクティス

保存場所

# Recommended: Project-local .venv
project/
├── .venv/        # Virtual environment here
├── src/
├── tests/
└── pyproject.toml

# uv creates .venv by default
uv venv

# Explicit location
uv venv .venv
python -m venv .venv

.gitignore

# Virtual environments
.venv/
venv/
ENV/
env/

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python

# Distribution
build/
dist/
*.egg-info/

# IDE
.idea/
.vscode/
*.swp
*.swo

# Testing
.pytest_cache/
.coverage
htmlcov/
.mypy_cache/

# Ruff
.ruff_cache/

有効化（必要な場合）

# Usually not needed with uv - just use `uv run`

# Linux/macOS
source .venv/bin/activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

# Windows (cmd)
.venv\Scripts\activate.bat

# Deactivate
deactivate

パッケージの公開

ビルドと公開

# Build with uv
uv build

# Publish to PyPI
uv publish

# Or with twine
pip install twine
twine upload dist/*

# Test PyPI first
twine upload --repository testpypi dist/*

バージョン管理

# pyproject.toml - dynamic version from __init__.py
[project]
dynamic = ["version"]

[tool.hatch.version]
path = "src/my_package/__init__.py"

# src/my_package/__init__.py
__version__ = "1.0.0"