uv-run

UV Run

uv で Python スクリプトを実行します。手動で venv を有効化する必要はありません。

このスキルを使用するタイミング

次の場合にこのスキルを使用してください…	次の場合は用途を絞った関連スキルを使用してください…
プロジェクトのコンテキストがなく、uv run script.py で単発のスクリプトを実行する	プロジェクトに長期的に使用する依存関係を追加する場合 — uv-project-management を使用します
自己完結型スクリプトに PEP 723 のインラインメタデータや --with の依存関係を埋め込む	グローバル CLI ツールをインストールする場合（uv tool install / uvx）— uv-tool-management を使用します
手動で有効化せずに、プロジェクトの venv 内でコマンドを実行する	プロジェクトの pyproject.toml やロックファイルを作成する場合 — uv-project-management を使用します

主な機能

• 直接実行：uv run script.py が環境を自動的に処理します
• 一時的な依存関係：単発の用途には uv run --with requests script.py を使用します
• インライン依存関係：自己完結型スクリプト向けの PEP 723 メタデータブロック
• 一時的なツール：uvx tool で CLI ツールをインストールせずに実行します

基本的なコマンド

スクリプトの実行

# Run script (uv manages environment automatically)
uv run script.py

# Run with arguments
uv run script.py --input data.csv --output results.json

# Run a specific module
uv run -m http.server 8000

# Run with specific Python version
uv run --python 3.12 script.py

一時的な依存関係

プロジェクトを変更せずに、1 回の実行に限って依存関係を追加します：

# Single dependency
uv run --with requests fetch_data.py

# Multiple dependencies
uv run --with requests --with rich api_client.py

# Version constraints
uv run --with 'requests>=2.31' --with 'rich>12,<14' script.py

# Combine with project dependencies
uv run --with pytest-benchmark pytest  # Add benchmark to existing pytest

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

依存関係を埋め込んだ自己完結型スクリプトを作成します：

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "requests>=2.31",
#   "rich>=13.0",
# ]
# ///

import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.json())

直接実行します：

uv run script.py

# Or make executable:
chmod +x script.py
./script.py

スクリプトの依存関係の管理

# Initialize script with metadata
uv init --script example.py --python 3.12

# Add dependency to script
uv add --script example.py requests rich

# Lock script dependencies for reproducibility
uv lock --script example.py

一時的なツールの実行（uvx）

CLI ツールをインストールせずに実行します：

# Run tool once
uvx pycowsay "Hello from uv!"
uvx httpie https://api.github.com
uvx ruff check .

# With specific version
uvx [email protected] check .

# uvx is shorthand for:
uv tool run pycowsay "Hello"

シバンのパターン

自己完結型の実行可能スクリプト

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["click", "rich"]
# ///

import click
from rich import print

@click.command()
@click.argument('name')
def hello(name):
    print(f"[green]Hello, {name}![/green]")

if __name__ == "__main__":
    hello()

Python のバージョン要件を指定したスクリプト

#!/usr/bin/env -S uv run --script --python 3.12
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///

import httpx
# Uses Python 3.12+ features

パターンの使い分け

シナリオ	方法
手早く済ませる単発のタスク	uv run --with pkg script.py
再利用可能なスクリプト	インライン依存関係（PEP 723）
共有可能なユーティリティ	PEP 723 + シバン
チームでの共同作業	インライン依存関係 + uv lock --script
CLI ツールを 1 回だけ実行する	uvx tool
プロジェクトのスクリプト	uv run（プロジェクトの依存関係を使用）

uvx と uv run --with の比較

• uvx tool：インストールせずに CLI ツールを実行します（例：uvx ruff check .）
• uv run --with pkg：一時的な依存関係を使ってスクリプトを実行します（例：uv run --with requests script.py）

# Run a tool (CLI application)
uvx httpie https://api.github.com

# Run a script with dependencies
uv run --with httpx api_test.py

プロファイリングとデバッグ

# CPU profiling
uv run python -m cProfile -s cumtime script.py | head -20

# Line-by-line profiling (temporary dependency)
uv run --with line-profiler kernprof -l -v script.py

# Memory profiling
uv run --with memory-profiler python -m memory_profiler script.py

# Real-time profiling (ephemeral tool)
uvx py-spy top -- python script.py

# Quick profiling
uv run --with scalene python -m scalene script.py

関連項目

• uv-project-management - プロジェクトの依存関係とロックファイル
• uv-tool-management - CLI ツールのグローバルインストール
• python-development - Python 言語の基本的なパターン

参考資料

• 公式ドキュメント：https://docs.astral.sh/uv/guides/scripts/
• PEP 723：https://peps.python.org/pep-0723/
• ツール：https://docs.astral.sh/uv/guides/tools/