uv

UV - Python パッケージマネージャースキル

概要

UV は Rust で記述された、非常に高速な Python パッケージおよびプロジェクトマネージャーです。このスキルでは、Python 開発における UV の使い方を、特に MCP（Model Context Protocol）サーバーとの連携や最新のツール管理ワークフローに焦点を当てて解説します。

UV は pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv など複数のツールを置き換え、インテリジェントなキャッシュと並列処理によって 10〜100 倍のパフォーマンスを実現します。

バージョンについて

推奨バージョン：UV 0.9.7 以降（2025 年 10 月時点の最新版）

開始する前に、UV のバージョンを確認してください。

uv --version

バージョン固有の重要な変更点：

• UV 0.9.6 以降：Python 3.14 がデフォルトになりました（以前は 3.13）
• UV 0.9.6 以降：フリースレッド版 Python 3.14 以降が、明示的なオプトインなしでサポートされます
• UV 0.9.6 以降：ビルド成果物をクリーンアップする uv build --clear フラグを利用できます
• UV 0.9.7 以降：tar／ZIP アーカイブ処理のセキュリティ更新

バージョンが 0.9.0 より古い場合は、最適な環境で使用できるようアップグレードしてください。

# Using pip
pip install --upgrade uv

# Or reinstall using official installer
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Unix/Mac
curl -LsSf https://astral.sh/uv/install.sh | sh

バージョン情報と移行ガイダンスについて詳しくは、最近の変更点リファレンスを参照してください。

このスキルを使用する場面

次の場合に、このスキルを使用してください。

• Python 仮想環境のセットアップや Python バージョンの管理
• Python CLI ツール（開発ツール、ユーティリティ）のインストールと管理
• UVX での MCP サーバーの実行
• パッケージの実行に uv tool install と uvx のどちらを使うかの判断
• MCP サーバー連携に向けた VS Code やその他の IDE の設定
• pip、pipx、poetry から UV への移行
• UV 関連の問題のトラブルシューティング

次の場合は、このスキルを使用しないでください。

• 基本的な Python パッケージのインストールだけが必要な場合（標準の pip ドキュメントで十分なことがあります）
• レガシーな Python 2.x プロジェクトを扱う場合

基本概念

1. UV コマンドの概要

UV は、用途に応じて複数のコマンドを提供します。

コマンド	用途	例
uv pip install	現在の環境にパッケージをインストールする	uv pip install requests
uv tool install	分離された環境で CLI ツールをグローバルにインストールする	uv tool install black
uvx	一時的な環境でパッケージを実行する	uvx mcp-server-sqlite
uv venv	仮想環境を作成する	uv venv .venv
uv python install	Python バージョンをインストールする	uv python install 3.12

2. Tool と UVX の選択フローチャート

Need to run a Python package?
|
├─ Use daily/frequently?
|  └─ YES → `uv tool install package`
|     Examples: black, pytest, flake8, mypy
|
├─ MCP server?
|  └─ YES → `uvx package` or `uvx --from path script.py`
|     Examples: mcp-server-sqlite, custom MCP servers
|
├─ Testing/one-off execution?
|  └─ YES → `uvx package`
|     Examples: testing new tools, version comparison
|
└─ Local development script?
   └─ YES → `uvx --from . script.py`
      Examples: project-specific scripts

3. MCP サーバーの実行パターン

公開済みパッケージ（作業ディレクトリは不要）：

{
  "servers": {
    "sqlite": {
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "/path/to/db"]
    }
  }
}

ローカル開発（--from フラグを使用）：

{
  "servers": {
    "my-server": {
      "command": "uvx",
      "args": [
        "--from", "/absolute/path/to/project",
        "server.py",
        "--config", "config.json"
      ]
    }
  }
}

重要なポイント：--from フラグ自体が、UVX における作業ディレクトリの指定です。

4. 仮想環境の管理

UV は Python 組み込みの venv とシームレスに連携します。

# Create virtual environment
python -m venv .venv

# Activate (Windows Git Bash)
. .venv/Scripts/activate

# Activate (Windows CMD)
.venv\Scripts\activate.bat

# Activate (Linux/Mac)
source .venv/bin/activate

# Install packages with UV
uv pip install -r requirements.txt

よく使うワークフロー

開発ツールのセットアップ

# Install development tools once
uv tool install black
uv tool install flake8
uv tool install mypy
uv tool install pytest

# Use daily
black .
flake8 src/
mypy src/
pytest tests/

MCP サーバーの使用

# Test published MCP servers
uvx mcp-server-sqlite --db-path test.db
uvx mcp-server-git --repository /path/to/repo

# Local MCP server development
uvx --from /path/to/project server.py --env config.env

プロジェクトの初期化

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

# Add dependencies
uv add requests fastapi

# Run project
uv run python main.py

Python バージョンの管理

# List available Python versions
uv python list

# Install default Python version (3.14 in UV 0.9.6+)
uv python install

# Install specific Python version
uv python install 3.12
uv python install 3.13

# Use in project
uv python pin 3.12

注： UV 0.9.6 以降、Python 3.14 がデフォルトバージョンです。Python 3.13 以前が必要な場合は、バージョンを明示的に指定してください。

インラインスクリプトの依存関係（PEP 723）

UV では、Python スクリプトのコメント内に依存関係を直接定義できます。

# /// script
# dependencies = [
#   "requests",
#   "pandas",
# ]
# ///

import requests
import pandas as pd

# Your code here

依存関係を自動でインストールして実行します。

# UV installs dependencies automatically
uv run script.py

利点：

• 単一ファイルで完結するスクリプト
• pyproject.toml が不要
• 共有や配布が簡単
• ユーティリティや自動化に最適

MCP サーバー、Web アプリケーション、データ処理、CLI ツールなどを含む包括的な例については、インラインスクリプトメタデータのリファレンスを参照してください。

連携パターン

VS Code の MCP 設定

.vscode/mcp.json またはユーザー設定の場合：

{
  "servers": {
    "published-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-sqlite", "--db-path", "${workspaceFolder}/db.sqlite"]
    },
    "local-dev": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "${workspaceFolder}",
        "src/server.py"
      ]
    }
  }
}

Continue IDE の設定

.continue/config.json の場合：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["mcp-server-fetch"]
        }
      }
    ]
  }
}

GitHub Actions CI/CD

- name: Setup UV
  uses: astral-sh/setup-uv@v1

- name: Install dependencies
  run: uv pip install -r requirements.txt

- name: Run tests
  run: uv run pytest

ベストプラクティス

ツール管理

推奨事項：

• 頻繁に使用する開発ツールには uv tool install を使用します
• MCP サーバーには uvx を使用します（コミュニティの慣習に従います）
• ツールはそれぞれ独立した環境に保ちます
• uv tool upgrade --all で定期的にツールをアップグレードします

避けるべき事項：

• CLI ツールにグローバルな pip を使用しないでください（依存関係の競合を引き起こします）
• MCP サーバーを uv tool install でインストールしないでください（コミュニティの慣習に反します）
• 日常的な開発ツールに uvx を使用しないでください（不要なオーバーヘッドが生じます）
• pip と uv によるツールのインストールを混在させないでください

MCP サーバーのパターン

推奨事項：

• すべての MCP サーバーの実行に UVX を使用します
• ローカル開発には --from を使用します
• 本番環境ではバージョンを固定します（[email protected]）
• 設定には環境変数を使用します

避けるべき事項：

• MCP サーバーをグローバルにインストールしないでください
• 作業ディレクトリの指定方法を混在させないでください
• 本番環境で @latest を使用しないでください（不安定です）
• --from で絶対パスを指定し忘れないでください

仮想環境

推奨事項：

• プロジェクト環境には python -m venv を使用します
• パッケージをインストールする前に環境を有効化します
• より高速なパッケージのインストールには uv pip install を使用します
• README に有効化コマンドを記載します

避けるべき事項：

• パッケージをグローバルにインストールしないでください
• venv とシステムの Python パッケージを混在させないでください
• 開発前に環境を有効化し忘れないでください
• .venv ディレクトリをバージョン管理にコミットしないでください

パフォーマンス特性

UV のパフォーマンス上の利点：

• パッケージ操作が pip より 10～100 倍高速
• 並列ダウンロードとインストール
• 重複排除機能を備えたグローバルキャッシュ
• Rust を活用した依存関係の解決
• ハードリンクによるディスク効率の高いストレージ

一般的な操作時間：

• パッケージのインストール：pip より 100～1000 倍高速
• 依存関係の解決：キャッシュ済みパッケージならほぼ瞬時
• 仮想環境の作成：1 秒未満
• UVX の初回実行：パッケージのダウンロード時間＋実行時間
• キャッシュ済みの UVX 実行：起動まで 1 秒未満

トラブルシューティング

よくある問題

「spawn uvx ENOENT」エラー：

• UV／UVX が PATH にありません
• 解決策：UV を再インストールするか、手動で PATH に追加します

パッケージが見つからない：

• PyPI でパッケージ名を確認します
• ローカル開発の場合は、--from のパスを確認します
• pyproject.toml が存在することを確認します

権限エラー：

• UV のキャッシュディレクトリに書き込み権限がありません
• 解決策：~/.cache/uv/ の権限を確認します

バージョンの競合：

• 複数の Python バージョンが存在します
• 解決策：uv python pin を使用してプロジェクトのバージョンを設定します

詳しいトラブルシューティングについては、以下を参照してください：

• インストールとセットアップのリファレンス
• ツール管理のリファレンス
• MCP 統合のリファレンス

リファレンスドキュメント

このスキルには、詳細なリファレンスドキュメントが含まれています：

1. 最近の変更 ⭐ NEW

   • 最新バージョンの情報（0.9.7 以降）
   • Python 3.14 のデフォルト設定とフリースレッド対応
   • 新機能と互換性を破る変更
   • バージョン互換性マトリックス
   • アップグレードのガイダンス

2. インストールとセットアップ

   • インストール方法（Windows、Linux、Mac）
   • 仮想環境のセットアップ
   • プラットフォーム固有の考慮事項

3. ツール管理

   • UV tool install と UVX の比較
   • 永続的な実行と一時的な実行
   • メンテナンスのワークフロー

4. MCP 統合

   • 公開済みパッケージのパターン
   • --from を使用したローカル開発
   • VS Code と IDE の設定

5. Python 環境

   • Python バージョン管理
   • システムパス（pyenv、uv、システム）
   • クロスプラットフォーム互換性

6. インラインスクリプトのメタデータ

   • コメント内の PEP 723 インライン依存関係
   • 依存関係を自動管理する単一ファイルのスクリプト
   • MCP サーバー、ウェブアプリ、CLI ツール
   • ベストプラクティスとトラブルシューティング

7. 例

   • 実際の GitHub 設定
   • 一般的なワークフローパターン
   • 避けるべきアンチパターン

外部リソース

• UV 公式ドキュメント：https://docs.astral.sh/uv/
• UV GitHub リポジトリ：https://github.com/astral-sh/uv
• MCP 公式ドキュメント：https://modelcontextprotocol.io/
• MCP サーバーリポジトリ：https://github.com/modelcontextprotocol/servers
• VS Code の MCP サポート：https://code.visualstudio.com/docs/copilot/chat/mcp-servers

移行ガイド

pip からの移行

# Old way
pip install requests

# New way
uv pip install requests

pipx からの移行

# Old way
pipx install black

# New way
uv tool install black

poetry からの移行

# Old way
poetry add requests
poetry install

# New way
uv add requests
uv sync

まとめ

UV は、Python パッケージ管理の統一された、高速でモダンなアプローチを提供します。UV を効果的に使用するためのポイントは次のとおりです。

1. ツールの用途を理解する：uv pip、uv tool、uvx はそれぞれ特定の用途に対応します
2. コミュニティのパターンに従う：MCP サーバーには UVX、開発ツールには uv tool を使用します
3. 分離を活用する：各ツールに専用の環境が用意されるため、競合を防げます
4. ローカル開発では --from を使用する：MCP サーバー開発に欠かせないパターンです
5. ツールを最新の状態に保つ：定期的なメンテナンスで問題を防げます

これらのパターンに従い、リファレンスドキュメントを活用することで、整理され、効率的で、保守しやすい Python 開発環境を実現できます。