Master the uv package manager for high-speed Python dependency management, virtual environments, and modern Python project workflows. Use it when setting up Python projects, managing dependencies, and optimizing Python development workflows with uv.
English | 日本語
Rustで書かれた非常に高速なPythonパッケージインストーラーとリゾルバーであるuvを使用した、モダンなPythonプロジェクト管理と依存関係ワークフローに関する包括的なガイド。
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# pipを使用（すでにPythonがある場合）
pip install uv
# Homebrewを使用（macOS）
brew install uv
# cargoを使用（Rustがある場合）
cargo install --git https://github.com/astral-sh/uv uv
uv --version
# uv 0.x.x
# 仮想環境付きの新しいプロジェクトを作成
uv init my-project
cd my-project
# または現在のディレクトリで作成
uv init .
# 初期化により作成される：
# - .python-version（Pythonバージョン）
# - pyproject.toml（プロジェクト設定）
# - README.md
# - .gitignore
# パッケージをインストール（必要に応じてvenvを作成）
uv add requests pandas
# dev依存関係をインストール
uv add --dev pytest black ruff
# requirements.txtからインストール
uv pip install -r requirements.txt
# pyproject.tomlからインストール
uv sync
# uvで仮想環境を作成
uv venv
# 特定のPythonバージョンで作成
uv venv --python 3.12
# カスタム名で作成
uv venv my-env
# システムサイトパッケージ付きで作成
uv venv --system-site-packages
# 場所を指定
uv venv /path/to/venv
# Linux/macOS
source .venv/bin/activate
# Windows (コマンドプロンプト)
.venv\Scripts\activate.bat
# Windows (PowerShell)
.venv\Scripts\Activate.ps1
# またはuv runを使用（アクティベーション不要）
uv run python script.py
uv run pytest
# Pythonスクリプトを実行（venvを自動アクティベート）
uv run python app.py
# インストールされたCLIツールを実行
uv run black .
uv run pytest
# 特定のPythonバージョンで実行
uv run --python 3.11 python script.py
# 引数を渡す
uv run python script.py --arg value
# パッケージを追加（pyproject.tomlに追加）
uv add requests
# バージョン制約付きで追加
uv add "django>=4.0,<5.0"
# 複数のパッケージを追加
uv add numpy pandas matplotlib
# dev依存関係を追加
uv add --dev pytest pytest-cov
# オプションの依存関係グループを追加
uv add --optional docs sphinx
# gitから追加
uv add git+https://github.com/user/repo.git
# 特定のrefでgitから追加
uv add git+https://github.com/user/repo.git@v1.0.0
# ローカルパスから追加
uv add ./local-package
# 編集可能なローカルパッケージを追加
uv add -e ./local-package
# パッケージを削除
uv remove requests
# dev依存関係を削除
uv remove --dev pytest
# 複数のパッケージを削除
uv remove numpy pandas matplotlib
# 特定のパッケージをアップグレード
uv add --upgrade requests
# すべてのパッケージをアップグレード
uv sync --upgrade
# パッケージを最新にアップグレード
uv add --upgrade requests
# アップグレードされるものを表示
uv tree --outdated
# uv.lockファイルを生成
uv lock
# ロックファイルを更新
uv lock --upgrade
# インストールせずにロック
uv lock --no-install
# 特定のパッケージをロック
uv lock --upgrade-package requests
# Pythonバージョンをインストール
uv python install 3.12
# 複数のバージョンをインストール
uv python install 3.11 3.12 3.13
# 最新バージョンをインストール
uv python install
# インストールされたバージョンをリスト
uv python list
# 利用可能なバージョンを検索
uv python list --all-versions
# プロジェクトのPythonバージョンを設定
uv python pin 3.12
# これにより.python-versionファイルが作成/更新される
# コマンドに特定のPythonバージョンを使用
uv --python 3.11 run python script.py
# 特定のバージョンでvenvを作成
uv venv --python 3.12
[project]
name = "my-project"
version = "0.1.0"
description = "My awesome project"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
"requests>=2.31.0",
"pydantic>=2.0.0",
"click>=8.1.0",
]
[project.optional-dependencies]
dev = [
"pytest>=7.4.0",
"pytest-cov>=4.1.0",
"black>=23.0.0",
"ruff>=0.1.0",
"mypy>=1.5.0",
]
docs = [
"sphinx>=7.0.0",
"sphinx-rtd-theme>=1.3.0",
]
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.uv]
dev-dependencies = [
# uvで管理される追加のdev依存関係
]
[tool.uv.sources]
# カスタムパッケージソース
my-package = { git = "https://github.com/user/repo.git" }
# requirements.txtから移行
uv add -r requirements.txt
# poetryから移行
# すでにpyproject.tomlがある場合、使用するだけ：
uv sync
# requirements.txtにエクスポート
uv pip freeze > requirements.txt
# ハッシュ付きでエクスポート
uv pip freeze --require-hashes > requirements.txt
# プロジェクト構造
# monorepo/
# packages/
# package-a/
# pyproject.toml
# package-b/
# pyproject.toml
# pyproject.toml（ルート）
# ルートpyproject.toml
[tool.uv.workspace]
members = ["packages/*"]
# すべてのワークスペースパッケージをインストール
uv sync
# ワークスペース依存関係を追加
uv add --path ./packages/package-a
# .github/workflows/test.yml
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
uses: astral-sh/setup-uv@v2
with:
enable-cache: true
- name: Set up Python
run: uv python install 3.12
- name: Install dependencies
run: uv sync --all-extras --dev
- name: Run tests
run: uv run pytest
- name: Run linting
run: |
uv run ruff check .
uv run black --check .
# Dockerfile
FROM python:3.12-slim
# uvをインストール
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
# 作業ディレクトリを設定
WORKDIR /app
# 依存関係ファイルをコピー
COPY pyproject.toml uv.lock ./
# 依存関係をインストール
RUN uv sync --frozen --no-dev
# アプリケーションコードをコピー
COPY . .
# アプリケーションを実行
CMD ["uv", "run", "python", "app.py"]
最適化されたマルチステージビルド：
# マルチステージDockerfile
FROM python:3.12-slim AS builder
# uvをインストール
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
WORKDIR /app
# venvに依存関係をインストール
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev --no-editable
# ランタイムステージ
FROM python:3.12-slim
WORKDIR /app
# ビルダーからvenvをコピー
COPY --from=builder /app/.venv .venv
COPY . .
# venvを使用
ENV PATH="/app/.venv/bin:$PATH"
CMD ["python", "app.py"]
# ロックファイル（uv.lock）を作成
uv lock
# ロックファイルからインストール（正確なバージョン）
uv sync --frozen
# インストールせずにロックファイルを更新
uv lock --no-install
# ロック内の特定のパッケージをアップグレード
uv lock --upgrade-package requests
# ロックファイルが最新かチェック
uv lock --check
# ロックファイルをrequirements.txtにエクスポート
uv export --format requirements-txt > requirements.txt
# セキュリティのためにハッシュ付きでエクスポート
uv export --format requirements-txt --hash > requirements.txt
# UVは自動的にグローバルキャッシュを使用：
# Linux: ~/.cache/uv
# macOS: ~/Library/Caches/uv
# Windows: %LOCALAPPDATA%\uv\cache
# キャッシュをクリア
uv cache clean
# キャッシュサイズをチェック
uv cache dir
# UVはデフォルトでパッケージを並列インストール
# 並列性を制御
uv pip install --jobs 4 package1 package2
# 並列なし（順次）
uv pip install --jobs 1 package
# キャッシュのみからインストール（ネットワークなし）
uv pip install --offline package
# ロックファイルからオフライン同期
uv sync --frozen --offline
# pip
python -m venv .venv
source .venv/bin/activate
pip install requests pandas numpy
# 〜30秒
# uv
uv venv
uv add requests pandas numpy
# 〜2秒（10〜15倍高速）
# poetry
poetry init
poetry add requests pandas
poetry install
# 〜20秒
# uv
uv init
uv add requests pandas
uv sync
# 〜3秒（6〜7倍高速）
# pip-tools
pip-compile requirements.in
pip-sync requirements.txt
# 〜15秒
# uv
uv lock
uv sync --frozen
# 〜2秒（7〜8倍高速）
# 完全なワークフロー
uv init my-project
cd my-project
# Pythonバージョンを設定
uv python pin 3.12
# 依存関係を追加
uv add fastapi uvicorn pydantic
# dev依存関係を追加
uv add --dev pytest black ruff mypy
# 構造を作成
mkdir -p src/my_project tests
# テストを実行
uv run pytest
# コードをフォーマット
uv run black .
uv run ruff check .
# リポジトリをクローン
git clone https://github.com/user/project.git
cd project
# 依存関係をインストール（venvを自動作成）
uv sync
# dev依存関係付きでインストール
uv sync --all-extras
# 依存関係を更新
uv lock --upgrade
# アプリケーションを実行
uv run python app.py
# テストを実行
uv run pytest
# 新しい依存関係を追加
uv add new-package
# 更新されたファイルをコミット
git add pyproject.toml uv.lock
git commit -m "Add new-package dependency"
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: uv-lock
name: uv lock
entry: uv lock
language: system
pass_filenames: false
- id: ruff
name: ruff
entry: uv run ruff check --fix
language: system
types: [python]
- id: black
name: black
entry: uv run black
language: system
types: [python]
// .vscode/settings.json
{
"python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
"python.terminal.activateEnvironment": true,
"python.testing.pytestEnabled": true,
"python.testing.pytestArgs": ["-v"],
"python.linting.enabled": true,
"python.formatting.provider": "black",
"[python]": {
"editor.defaultFormatter": "ms-python.black-formatter",
"editor.formatOnSave": true
}
}
# 問題: uvが見つからない
# 解決策: PATHに追加または再インストール
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
# 問題: 間違ったPythonバージョン
# 解決策: バージョンを明示的にピン留め
uv python pin 3.12
uv venv --python 3.12
# 問題: 依存関係の競合
# 解決策: 解決をチェック
uv lock --verbose
# 問題: キャッシュの問題
# 解決策: キャッシュをクリア
uv cache clean
# 問題: ロックファイルが同期していない
# 解決策: 再生成
uv lock --upgrade
# CIで凍結されたインストールを使用
uv sync --frozen
# 可能な場合はオフラインモードを使用
uv sync --offline
# 並列操作（自動）
# uvはデフォルトでこれを行う
# 環境間でキャッシュを再利用
# uvはグローバルにキャッシュを共有
# 解決をスキップするためにロックファイルを使用
uv sync --frozen # 解決をスキップ
# 以前
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# 以後
uv venv
uv pip install -r requirements.txt
# またはより良い方法：
uv init
uv add -r requirements.txt
# 以前
poetry install
poetry add requests
# 以後
uv sync
uv add requests
# 既存のpyproject.tomlを保持
# uvは[project]と[tool.poetry]セクションを読む
# 以前
pip-compile requirements.in
pip-sync requirements.txt
# 以後
uv lock
uv sync --frozen
# プロジェクト管理
uv init [PATH] # プロジェクトを初期化
uv add PACKAGE # 依存関係を追加
uv remove PACKAGE # 依存関係を削除
uv sync # 依存関係をインストール
uv lock # ロックファイルを作成/更新
# 仮想環境
uv venv [PATH] # venvを作成
uv run COMMAND # venv内で実行
# Python管理
uv python install VERSION # Pythonをインストール
uv python list # インストールされたPythonをリスト
uv python pin VERSION # Pythonバージョンをピン留め
# パッケージインストール（pip互換）
uv pip install PACKAGE # パッケージをインストール
uv pip uninstall PACKAGE # パッケージをアンインストール
uv pip freeze # インストール済みをリスト
uv pip list # パッケージをリスト
# ユーティリティ
uv cache clean # キャッシュをクリア
uv cache dir # キャッシュ場所を表示
uv --version # バージョンを表示
uv initで開始Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer