自分用Python環境管理uvコマンドのチートシート

python コンピュータ 開発 WSL Ubuntu PowerShell

この内容はPythonの開発時に使用するpip/venv/pyenvの代替ツールのチートシートになります。 自分用に作成したので、かなり偏った内容になっています。※Macについては私が使用していないので適当かもしれません。

1. 導入・インストール

インストール方法

OS コマンド 備考
macOS/Linux/WSL curl -LsSf https://astral.sh/uv/install.sh | sh 公式推奨
Windowsネイティブ powershell -c "irm https://astral.sh/uv/install.ps1 | iex" PowerShell

動作確認

# インストール確認
$ uv --version
# ヘルプ表示
$ uv --help

2. venv・pipからの移行

も簡単な方法

この方法では既存の仮想環境からpipの代わりにuv pipを使用する方法になります。

# 既存の仮想環境でpipの代わりにuv pipを使用
$ source .venv/bin/activate
$ uv pip install -r requirements.txt
# 以降はuvを使用していく

推奨方法

# 既存プロジェクトディレクトリにて
# requirements.txtを自動変換
$ uv init
# 環境構築・依存関係インストール                    
$ uv sync                    
# requirements.txtを削除し、pyproject.toml/uv.lockを使用する

移行時コマンド表

※以下、実際のpackageをインストールする例ではrequestsを使用しています。

従来のコマンド uvコマンド 備考
python -m venv .venv uv venv Pythonバージョン指定可能
source .venv/bin/activate source .venv/bin/activate アクティベーションは同じ（uvはしなくても良い）
pip install requests uv pip install requests または uv add requests
pip install -r requirements.txt uv pip install -r requirements.txt または uv sync
pip freeze > requirements.txt uv pip freeze または uv lock
pip uninstall requests uv pip uninstall requests または uv remove requests
pip list uv pip list 機能的に同等

3. 移行における注意点

あんまり使用はしないと思いますが、以下のような対応ができます。

# 環境の復元
$ uv venv --force            # 仮想環境再作成
$ uv sync --reinstall        # 依存関係再インストール

# キャッシュ関連
$ uv cache clean             # キャッシュクリア
$ uv cache clean <package>   # 特定パッケージのキャッシュクリア

# バージョンの競合関連
$ uv lock --verbose          # 詳細な競合情報
$ uv tree                    # 依存関係ツリー表示

4. uvコマンド一覧

Pythonバージョン関連

コマンド 概要 例
uv python install <ver> 指定バージョンをダウンロード・インストール uv python install 3.12
uv python list インストール済みPython一覧 uv python list
uv python pin <ver> プロジェクトのPythonバージョン固定 uv python pin 3.11
uv python find <ver> 指定バージョンのパス検索 uv python find 3.11

仮想環境関連

コマンド 概要 例
uv venv [dir] 仮想環境作成 uv venv .venv --python 3.11
uv venv --python <ver> 指定バージョンで作成 uv venv --python 3.12

プロジェクト管理

コマンド 概要 例
uv init [name] プロジェクト初期化 uv init my-project --python 3.11
uv add <package> 依存関係追加（pyproject.toml更新） uv add requests pandas
uv add --dev <package> 開発用依存関係追加 uv add --dev pytest black
uv remove <package> 依存関係削除 uv remove requests
uv sync 環境をlockfileと同期 uv sync --no-dev
uv lock lockfile生成・更新 uv lock --upgrade

パッケージ管理（pip互換）

コマンド 概要 例
uv pip install <pkg> パッケージインストール uv pip install requests
uv pip install -r <file> requirements.txtからインストール uv pip install -r requirements.txt
uv pip list インストール済みパッケージ一覧 uv pip list
uv pip freeze 現在の依存関係出力 uv pip freeze > requirements.txt
uv pip uninstall <pkg> パッケージアンインストール uv pip uninstall requests

実行・スクリプト

コマンド 概要 例
uv run <script> 仮想環境でスクリプト実行 uv run main.py
uv run -m <module> モジュール実行 uv run -m pytest
uv run <command> 任意のコマンド実行 uv run black .
uvx <tool> 一時環境でツール実行 uvx black .

ビルド・公開

コマンド 概要 例
uv build wheel/sdist作成 uv build --wheel
uv publish PyPIへ公開 uv publish --repository testpypi

その他

コマンド 概要 例
uv cache clean キャッシュクリア uv cache clean
uv tree 依存関係ツリー表示 uv tree
uv export lockfileをrequirements.txt形式で出力 uv export > requirements.txt

5. 使用方法別ストーリー

ローカルでの新規プロジェクトの進め方

# プロジェクト作成（ディレクトリ自動作成）
$ uv init my-project --python 3.11
$ cd my-project

# 依存関係追加
$ uv add requests pandas

# Git管理（必要あれば）
$ git init
$ git add .
$ git commit -m "Initial project setup"

# 開発開始
$ uv run main.py

GitHubリポジトリクローン時の進め方

$ git clone <repository>
$ cd <project>
$ uv sync

6. エイリアス設定例

# ~/.bashrc または ~/.zshrc に追加
alias uvp='uv pip'             # pip互換コマンド
alias uvr='uv run'             # 実行コマンド
alias uvs='uv sync'            # 環境同期
alias uva='uv add'             # 依存関係追加
alias uvl='uv lock'            # lockfile更新

7. 参考リンク

公式ドキュメント

自分用クイックリファレンス

目的 コマンド 備考
新規プロジェクト uv init my-project ディレクトリ自動作成
既存プロジェクト初期化 uv init 現在のディレクトリで
依存関係追加 uv add requests pyproject.toml自動更新
環境構築 uv sync lockfileから完全再現
スクリプト実行 uv run script.py 仮想環境で自動実行
テスト実行 uv run pytest 開発用依存関係も利用
高速pip uv pip install requests 10-100倍高速
Pythonのバージョン管理 uv python install 3.11 バージョン管理統合