uv-skill

uv スキル

Astral（Ruff の開発元）による、非常に高速な Python パッケージおよびプロジェクト管理ツールです。

概要

uv は、次のツールを置き換える単一のツールです。

• pip/pip-tools - パッケージのインストールと依存関係の解決
• virtualenv/venv - 仮想環境の作成
• pyenv - Python バージョンの管理
• pipx - ツールのインストールと実行
• poetry/pdm - プロジェクトと依存関係の管理
• twine - パッケージの公開

主な機能：

• pip より 10～100 倍高速
• 再現可能なビルドを実現するユニバーサルロックファイル（uv.lock）
• Python バージョンの自動管理
• ツールの実行機能を内蔵（uvx）
• PEP 723 のインラインスクリプト依存関係
• pip とそのまま置き換えられる互換性

クイックリファレンス

タスク	コマンド
新規プロジェクト	uv init
新規ライブラリ	uv init --lib
パッケージを追加	uv add <pkg>
開発用依存関係を追加	uv add --dev <pkg>
パッケージを削除	uv remove <pkg>
すべての依存関係をインストール	uv sync
インストール（CI／本番環境）	uv sync --locked
コマンドを実行	uv run <cmd>
ツールを実行（インストール不要）	uvx <tool>
Python をインストール	uv python install 3.12
Python バージョンを固定	uv python pin 3.12
すべての依存関係を更新	uv lock --upgrade
1 つのパッケージを更新	uv lock --upgrade-package <pkg>
依存関係ツリーを表示	uv tree
パッケージをビルド	uv build
PyPI に公開	uv publish

クイックスタート

インストール

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

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

# Via pip/pipx
pipx install uv
pip install uv

# Homebrew
brew install uv

シェル補完

# Bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

# Zsh
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

# Fish
echo 'uv generate-shell-completion fish | source' > ~/.config/fish/completions/uv.fish

基本コマンド

1. プロジェクトの開始

# Create new project
uv init my-project          # Application (default)
uv init --lib my-library    # Library (src layout, build backend)
uv init --app my-app        # Explicit application

# Set Python version
uv python pin 3.12          # Creates .python-version

# Install Python if needed
uv python install 3.12

2. 依存関係の管理

# Add packages
uv add requests flask       # Production dependencies
uv add --dev pytest ruff    # Development dependencies
uv add --group test pytest  # Specific dependency group
uv add --optional api flask # Optional extra
uv add "httpx>=0.20"        # With version constraint

# Remove packages
uv remove requests
uv remove --dev pytest

# Update packages
uv lock --upgrade                    # All packages
uv lock --upgrade-package requests   # Single package

# View dependencies
uv tree                     # Full tree
uv tree --depth 2           # Limited depth

3. 環境の同期

# Install all dependencies
uv sync                     # Default (includes dev)
uv sync --locked            # CI/production (strict)
uv sync --frozen            # Don't update lockfile
uv sync --no-dev            # Exclude dev dependencies
uv sync --all-extras        # Include optional extras

4. コードの実行

# Run in project environment
uv run python script.py
uv run pytest
uv run flask run

# Run with temporary dependency
uv run --with pandas script.py

# Run tools without installing (uvx)
uvx ruff check .
uvx black --check .
uvx --from httpie http https://example.com

5. Python バージョンの管理

# Install Python versions
uv python install           # Latest version
uv python install 3.12      # Specific version
uv python install 3.11 3.12 3.13  # Multiple

# List versions
uv python list
uv python list --only-installed

# Pin version
uv python pin 3.12          # Project (.python-version)
uv python pin --global 3.12 # User default

# Find Python
uv python find
uv python find ">=3.11"

6. 仮想環境

# Create (usually automatic)
uv venv                     # Creates .venv
uv venv my-env              # Custom name
uv venv --python 3.12       # Specific Python

# Activate (optional - uv run auto-detects)
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows

7. グローバルツール

# Install tools globally
uv tool install ruff
uv tool install "ruff==0.5.0"
uv tool install --python 3.12 mypy

# Manage tools
uv tool list
uv tool upgrade ruff
uv tool upgrade --all
uv tool uninstall ruff

# Setup PATH
uv tool update-shell

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

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

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

# Run script (dependencies auto-installed)
uv run example.py

スクリプト形式：

# /// script
# requires-python = ">=3.12"
# dependencies = [
#   "requests<3",
#   "rich",
# ]
# ///

import requests
from rich import print
print(requests.get("https://api.example.com").json())

pip 互換インターフェース

# Install packages (requires virtual environment)
uv pip install flask
uv pip install -r requirements.txt
uv pip install -e .         # Editable install

# Uninstall
uv pip uninstall flask

# Compile requirements
uv pip compile requirements.in -o requirements.txt

# Sync from requirements
uv pip sync requirements.txt

# Freeze environment
uv pip freeze

ビルドと公開

# Build distributions
uv build                    # Creates dist/ with wheel and sdist

# Publish to PyPI
uv publish                  # Requires authentication setup

# Authenticate
uv auth login pypi          # Interactive login
uv auth login pypi --token  # API token

プロジェクト構成

my-project/
├── pyproject.toml          # Project definition (required)
├── uv.lock                 # Lock file (auto-generated)
├── .venv/                  # Virtual environment (gitignored)
├── .python-version         # Python version pin (optional)
└── src/
    └── my_project/
        └── __init__.py

pyproject.toml の例

[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

[project.optional-dependencies]
api = ["fastapi", "uvicorn"]
dev = ["pytest", "ruff"]

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

[dependency-groups]
dev = ["pytest>=8", "ruff", "mypy"]
test = ["pytest-cov"]
docs = ["sphinx", "myst-parser"]

[tool.uv]
dev-dependencies = ["pytest", "ruff"]  # Alternative to dependency-groups
default-groups = ["dev"]

[tool.uv.sources]
# Git dependency
my-lib = { git = "https://github.com/user/my-lib" }
# Local path
local-pkg = { path = "./packages/local-pkg" }
# Specific index
torch = { index = "pytorch" }

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

設定

設定ファイル

プロジェクトレベル（優先度が最も高い）：

• uv.toml - 単独の設定ファイル（推奨）
• pyproject.toml - [tool.uv] セクション内

ユーザーレベル：

• ~/.config/uv/uv.toml（macOS/Linux）
• %APPDATA%\uv\uv.toml（Windows）

主な環境変数

変数	用途
UV_CACHE_DIR	キャッシュディレクトリの場所
UV_PYTHON	デフォルトの Python バージョン
UV_INDEX_URL	デフォルトのパッケージインデックス
UV_NO_CACHE	キャッシュを無効化
UV_FROZEN	更新せずにロックファイルを使用
UV_LOCKED	ロックファイルが変更されていないことを確認
UV_COMPILE_BYTECODE	.pyc ファイルにコンパイル
UV_LINK_MODE	パッケージのリンク方式（copy、hardlink、symlink）

よくあるワークフロー

新規プロジェクトのセットアップ

# Create and enter project
uv init my-project
cd my-project

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

# Run application
uv run flask run

# Run tests
uv run pytest

既存プロジェクト（requirements.txt から）

# Initialize uv project
uv init

# Import dependencies from requirements.txt
uv add $(cat requirements.txt | grep -v "^#" | tr '\n' ' ')

# Or use pip interface
uv venv
uv pip install -r requirements.txt

CI/CD パイプライン

# GitHub Actions
- uses: astral-sh/setup-uv@v7
  with:
    enable-cache: true
- run: uv sync --locked
- run: uv run pytest

# GitLab CI
variables:
  UV_CACHE_DIR: .uv-cache
  UV_LINK_MODE: copy
image: ghcr.io/astral-sh/uv:latest
script:
  - uv sync --locked
  - uv run pytest

Docker

FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

WORKDIR /app
COPY pyproject.toml uv.lock ./

# Install dependencies only (for caching)
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-install-project

# Copy source and install project
COPY . .
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked

ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "-m", "my_app"]

direnv との連携

# .envrc
if has uv; then
  VIRTUAL_ENV="$(pwd)/.venv"
  if [[ ! -d "$VIRTUAL_ENV" ]]; then
    uv venv
  fi
  PATH_add "$VIRTUAL_ENV/bin"
  export VIRTUAL_ENV
fi

移行ガイド

pip + requirements.txt からの移行

# Option 1: Initialize new uv project and import dependencies
uv init
# Extract package names from requirements.txt
cat requirements.txt | grep -v "^#" | grep -v "^-e" | \
  cut -d'=' -f1 | cut -d'>' -f1 | xargs uv add

# Option 2: Keep using requirements.txt with uv's pip interface
uv venv
uv pip install -r requirements.txt

# Option 3: Generate lockfile from requirements.txt
uv pip compile requirements.in -o requirements.txt

主な違い：

• ロックには requirements.txt の代わりに uv.lock を使用します
• 依存関係の宣言には requirements.in の代わりに pyproject.toml を使用します
• 仮想環境を有効化する代わりに uv run を使用します

Poetry からの移行

# uv can read Poetry's pyproject.toml format
cd existing-poetry-project

# Initialize uv (keeps existing pyproject.toml)
uv sync

# Poetry sections are automatically recognized:
# [tool.poetry.dependencies] -> project dependencies
# [tool.poetry.group.dev.dependencies] -> dev dependencies

pyproject.toml の移行（任意ですが推奨）：

# Poetry format
[tool.poetry.dependencies]
python = "^3.11"
requests = "^2.28"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"

# Standard format (uv native)
[project]
requires-python = ">=3.11"
dependencies = ["requests>=2.28"]

[dependency-groups]
dev = ["pytest>=8.0"]

コマンドの対応関係：

Poetry	uv
poetry install	uv sync
poetry add requests	uv add requests
poetry add -D pytest	uv add --dev pytest
poetry remove requests	uv remove requests
poetry run pytest	uv run pytest
poetry lock	uv lock
poetry build	uv build
poetry publish	uv publish

Pipenv からの移行

# Convert Pipfile to requirements.txt first
pipenv requirements > requirements.txt
pipenv requirements --dev > requirements-dev.txt

# Initialize uv project and import
uv init
cat requirements.txt | grep -v "^#" | xargs uv add
cat requirements-dev.txt | grep -v "^#" | xargs uv add --dev

# Remove old Pipenv files after verification
rm Pipfile Pipfile.lock

コマンドの対応関係：

Pipenv	uv
pipenv install	uv sync
pipenv install requests	uv add requests
pipenv install --dev pytest	uv add --dev pytest
pipenv run pytest	uv run pytest
pipenv lock	uv lock
pipenv shell	source .venv/bin/activate（または uv run を使用）

pyenv から（Python バージョン管理のみ）

# Install Python versions with uv instead
uv python install 3.11 3.12 3.13

# Pin version for project (creates .python-version)
uv python pin 3.12

# List installed versions
uv python list --only-installed

# uv reads existing .python-version files from pyenv

注： pyenv と uv は併用できます。uv は pyenv でインストールされた Python を検出します。

conda から

uv は、以下について conda の代替にはなりません。

• Python 以外の依存関係（C ライブラリ、CUDA など）
• PyPI にない conda 固有のパッケージ

純粋な Python プロジェクトの場合：

# Export conda environment
conda list --export > conda-packages.txt

# Extract Python packages (filter conda-specific ones)
grep -v "^#" conda-packages.txt | grep -v "conda" | cut -d'=' -f1 > packages.txt

# Initialize uv and add packages
uv init
uv add $(cat packages.txt | tr '\n' ' ')

ハイブリッドなアプローチ： システム依存関係には conda、Python パッケージには uv を使用します。

# Conda for non-Python deps
conda create -n myenv python=3.12 cudatoolkit

# Activate conda env, then use uv
conda activate myenv
export UV_SYSTEM_PYTHON=1
uv pip install -r requirements.txt

よくある落とし穴

1. CI／本番環境で --locked を忘れる

# Wrong - may update lockfile unexpectedly
uv sync

# Correct - fails if lockfile is outdated (reproducible builds)
uv sync --locked

2. uv と pip のコマンドを混在させる

# Don't do this - breaks uv's dependency tracking
pip install some-package
source .venv/bin/activate && pip install another-package

# Do this instead - uv tracks all dependencies
uv add some-package
# Or use uv's pip interface if needed
uv pip install some-package

3. uv.lock をコミットしない

再現可能なビルドを実現するには、uv.lock ファイルをバージョン管理に必ずコミットしてください。 このファイルがないと、環境によって依存関係の解決結果が異なる場合があります。

# .gitignore - DON'T ignore uv.lock
.venv/
__pycache__/
# uv.lock  <-- DO NOT ADD THIS LINE

4. プロジェクト環境の外でコマンドを実行する

# Wrong - uses system Python, not project environment
python script.py
pytest

# Correct - runs within project's virtual environment
uv run python script.py
uv run pytest

5. uv.lock を手動で編集する

uv.lock を手動で編集しないでください。このファイルは uv によって自動生成され、管理されます。

# To update a specific package
uv lock --upgrade-package requests

# To upgrade all packages
uv lock --upgrade

# To regenerate from scratch
rm uv.lock && uv lock

6. --locked を使うべきところで --frozen を使う

# --frozen: Don't update lockfile, but don't verify it either
uv sync --frozen

# --locked: Verify lockfile matches pyproject.toml (use this in CI)
uv sync --locked

トラブルシューティング

よくある問題

問題	原因	解決策
No pyproject.toml	ディレクトリが違う	ルートに cd するか、uv init を実行します
パッケージが見つからない	インデックスが違う／入力ミス	名前を確認し、--index を試します
ロックファイルが古い	pyproject が変更された	uv lock を実行します
Resolver conflict	バージョンの競合	uv lock --upgrade を試します
Python のバージョンが一致しない	インストールされていない	uv python install 3.12 を実行します
ビルドに失敗する	依存関係が不足している	--no-build-isolation を試します
ハッシュが一致しない	キャッシュが破損している	uv cache clean を実行します
初回の実行が遅い	キャッシュが空	正常です。以降はキャッシュが使用されます

デバッグコマンド

# Check current environment
uv python find
uv pip list

# Verbose output
uv sync -v
uv sync -vv  # More verbose

# Check lockfile status
uv lock --check

# Clear cache
uv cache clean
uv cache prune --ci  # For CI environments

参考資料

• references/cli-commands.md - CLI リファレンスの完全版
• references/project-management.md - プロジェクトと依存関係の管理
• references/python-versions.md - Python バージョンの管理
• references/integrations.md - Docker、CI/CD、ツールの統合

外部リンク

• 公式ドキュメント：https://docs.astral.sh/uv/
• GitHub：https://github.com/astral-sh/uv
• Docker イメージ：https://github.com/astral-sh/uv/pkgs/container/uv
• 変更履歴：https://github.com/astral-sh/uv/blob/main/CHANGELOG.md