モダンPython開発環境：uv＋ruff＋pytest

上図はNotebookLMで作成しました。

はじめに

Pythonの開発環境構築は、長らく「pip + venv + flake8 + black」という組み合わせが定番でした。しかし、Rust製の高速ツールが台頭し、開発体験が劇的に向上しています。本記事では、Mac環境においてuv（パッケージ管理）、ruff（リンター/フォーマッター）、pytest（テスト）という現代的な3点セットで開発環境を構築する方法を解説します。

なぜこの組み合わせなのか

従来のツールチェーンには以下の課題がありました。

• pip: 依存関係の解決が遅い、ロックファイルの標準サポートがない
• venv: 機能は十分だが、作成・管理が煩雑
• flake8 + black + isort: 3つのツールの設定を個別に管理する必要がある

uv + ruff + pytestの組み合わせは、これらの課題を解決します。

• uv: pip比で10〜100倍高速、ロックファイル対応、仮想環境管理も統合
• ruff: Rustで実装された高速なリンター・フォーマッター
• pytest: 変わらず最強のテストフレームワーク

uvのインストールと設定

まずuvをインストールします。Macではbrewが最も簡単です。

# Homebrewでインストール
brew install uv

インストール後、バージョンを確認しましょう。

uv --version
# uv 0.8.x

プロジェクトの作成

新規プロジェクトを作成する場合

# プロジェクトディレクトリを作成
uv init my-project
cd my-project

これにより、以下のファイルが生成されます。

• pyproject.toml: プロジェクト設定ファイル
• .python-version: 使用するPythonバージョン
• README.md: READMEファイル

既存プロジェクトの場合は、ディレクトリ内でuv initを実行するか、手動でpyproject.tomlを作成します。

仮想環境とパッケージ管理

uvは仮想環境の作成からパッケージのインストールまでシームレスに行えます。

# 仮想環境を作成（.venvディレクトリに作成される）
uv venv

# パッケージをインストール
uv add requests
uv add pandas numpy

# 開発用依存関係を追加
uv add --dev pytest ruff

# ロックファイルから依存関係を同期
uv sync

uv addを実行すると、pyproject.tomlの依存関係が更新され、uv.lockというロックファイルが生成されます。このロックファイルをGitで管理することで、チーム全員が同じバージョンの依存関係を使用できます。

ruffのセットアップ

ruffは、Pythonのリンターとフォーマッターを統合したツールです。Astral社（uvと同じ開発元）が開発しており、Rustで書かれているため非常に高速です。

インストール

uvで開発依存関係としてインストール済みですが、グローバルにも入れておくと便利です。

# プロジェクト内（uvで管理）
uv add --dev ruff

# グローバルインストール（お好みで）
uv tool install ruff
# もしくは
brew install ruff

設定

pyproject.tomlにruffの設定を追加します。

[tool.ruff]
# 対象とするPythonバージョン
target-version = "py312"

# 1行の最大文字数
line-length = 88

# チェック対象から除外するディレクトリ
exclude = [
    ".venv",
    "__pycache__",
    "migrations",
]

[tool.ruff.lint]
# 有効にするルール
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "F",    # Pyflakes
    "I",    # isort
    "B",    # flake8-bugbear
]

# 無視するルール
ignore = []

[tool.ruff.format]
# クォートスタイル
quote-style = "double"

# インデントスタイル
indent-style = "space"

詳しくは以下の公式サイトに載っています。

使い方

# リントを実行
uv run ruff check .

# 自動修正可能な問題を修正
uv run ruff check --fix .

# フォーマットを実行
uv run ruff format .

# フォーマットのチェックのみ（変更なし）
uv run ruff format --check .

uv runを使うことで、仮想環境を明示的にactivateせずにコマンドを実行できます。

pytestの設定

pytestは言わずと知れたPythonのテストフレームワークです。シンプルな記述で強力なテストが書けます。

インストール

uv add --dev pytest pytest-cov

pytest-covはカバレッジ計測用のプラグインです。

設定

pyproject.tomlに設定を追加します。

[tool.pytest.ini_options]
# テストファイルの検索パターン
testpaths = ["tests"]

# 出力オプション
addopts = "-v --tb=short"

# Pythonファイルのパターン
python_files = "test_*.py"

# テスト関数のパターン
python_functions = "test_*"

ディレクトリ構成

推奨するディレクトリ構成は以下の通りです。

my-project/
├── pyproject.toml
├── uv.lock
├── src/
│   └── my_project/
│       ├── __init__.py
│       └── main.py
└── tests/
    ├── __init__.py
    └── test_main.py

tests/にテストファイルを全て置くようにします。

テストの実行

# すべてのテストを実行
uv run pytest

# 特定のファイルのみ
uv run pytest tests/test_main.py

# カバレッジ付きで実行
uv run pytest --cov=src --cov-report=html

HTMLレポートのデフォルト出力先は、実行したカレントディレクトリ直下の htmlcov/ です。

統合：pyproject.tomlの全体像

ここまでの設定をまとめたpyproject.tomlの全体像です。

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.31.0",
]

[dependency-groups]
dev = [
    "pytest>=9.0.2",
    "pytest-cov>=7.0.0",
    "ruff>=0.14.10",
]

[tool.ruff]
target-version = "py312"
line-length = 88
exclude = [".venv", "__pycache__"]

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B"]

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

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --tb=short"
python_files = "test_*.py"
python_functions = "test_*"

開発ワークフロー

日常的な開発フローは以下のようになります。

# 1. コードを書く
# ...

# 2. フォーマットとリント
uv run ruff format .
uv run ruff check --fix .

# 3. テストを実行
uv run pytest

# 4. コミット
git add .
git commit -m "feat: add new feature"

VS Codeとの連携

VS Codeを使用している場合、以下の拡張機能をインストールすることで、より快適な開発体験が得られます：

• Ruff: 公式拡張機能。保存時の自動フォーマット、リアルタイムのリントが可能
• Python: Microsoft公式。pytestとの連携、デバッグ機能を提供

.vscode/settings.jsonの推奨設定：

{
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports.ruff": "explicit"
        }
    },
    "python.testing.pytestEnabled": true,
    "python.testing.pytestArgs": ["tests"]
}

VS Codeのアドオンを入れて上記を設定すると、セーブした時に自動でフォーマットがかかるようになります。また、インポートの順序もcommand + .でクイック修正できます。

まとめ

uv + ruff + pytestの組み合わせは、2026年現在のPython開発における最適解の一つです。
特にuvとruffはどちらもAstral社が開発しており、連携がスムーズです。

まだ試していない方は、ぜひ新規プロジェクトから導入してみてください。