uvコマンドチートシート

以下は参照用にDeep Researchの出力をコピペしたものです。

Pythonパッケージ管理ツール uv チートシート

Python中級者向けに、パッケージ管理ツール uv の基本コマンドをまとめます。仮想環境の管理から依存関係の追加・ロックまで、開発ワークフローに沿った使い方を紹介します。

仮想環境の作成・管理

• 仮想環境の作成: uv venv コマンドで現在のディレクトリに .venv 環境を高速に作成します。

  $ uv venv               # カレントディレクトリに.venvを作成 (デフォルトPython使用)
  $ uv venv my_env        # my_envという名前の仮想環境フォルダを作成
  $ uv venv --python 3.11 # Python 3.11指定で仮想環境を作成:contentReference[oaicite:1]{index=1}
  

  --pythonオプションでPythonバージョンを指定できます（未インストールの場合は自動でダウンロードされます）。

• 仮想環境の自動検出: uvはデフォルトでカレントディレクトリ直下の.venvを検出し、以降のコマンドで利用します。もし仮想環境が存在しない場合、コマンド実行時に uv venv 実行を促されます。

• 仮想環境のアクティベート: 必要に応じて従来の方法でアクティブ化できます（Unix系: source .venv/bin/activate、Windows: .venv\Scripts\activate）。ただし、後述のuv runを使えばアクティブ化せずとも仮想環境内でコマンドを実行できます。

• 仮想環境の削除: 専用コマンドはありませんが、不要になったら .venv フォルダを手動で削除できます（環境構築はロックファイルから再現可能なため）。

パッケージのインストール・削除

• インストール (pipライクな操作): uv pip install は通常の pip install と同様に使え、現在の仮想環境にパッケージをインストールします。例：

  $ uv pip install flask            # Flaskをインストール:contentReference[oaicite:7]{index=7}
  $ uv pip install flask ruff       # 複数パッケージをまとめてインストール:contentReference[oaicite:8]{index=8}
  $ uv pip install 'requests==2.31.0' # バージョン指定インストール:contentReference[oaicite:9]{index=9}
  $ uv pip install "flask[dotenv]"  # エクストラ付きでインストール:contentReference[oaicite:10]{index=10}
  

  ※uv pip install -e . でカレントプロジェクトを編集可能モードでインストールすることもできます。

• アンインストール: uv pip uninstall <パッケージ> で仮想環境からパッケージを削除できます（複数指定も可）。例：

  $ uv pip uninstall flask          # Flaskをアンインストール:contentReference[oaicite:13]{index=13}
  $ uv pip uninstall flask ruff     # 複数パッケージをまとめて削除:contentReference[oaicite:14]{index=14}
  

• インストール済パッケージの確認:

  $ uv pip list       # インストール済パッケージを一覧表示:contentReference[oaicite:15]{index=15}
  $ uv pip freeze     # 要求仕様（requirements.txt形式）で一覧表示:contentReference[oaicite:16]{index=16}
  $ uv pip show numpy # 個別パッケージの詳細情報を表示:contentReference[oaicite:17]{index=17}
  $ uv pip check      # 依存関係の矛盾や欠如をチェック:contentReference[oaicite:18]{index=18}
  

requirementsファイルとの連携

• requirements.txtからのインストール: 既存のロックファイル（requirements.txt）がある場合、以下で環境を構築できます。

  $ uv pip install -r requirements.txt   # 要件ファイルからインストール:contentReference[oaicite:19]{index=19}
  

  この方法では既に環境に存在するパッケージの削除は行われないため、環境を正確に同期するには次項のsyncを使用します。

• 環境の同期 (pip-sync相当): ロックファイルに記載されたパッケージとバージョンに完全一致するよう環境を同期させるには uv pip sync を使います。

  $ uv pip sync requirements.txt   # requirements.txtどおりに環境を同期:contentReference[oaicite:22]{index=22}
  $ uv pip sync pyproject.toml     # pyproject.toml（とロックファイル）どおりに同期:contentReference[oaicite:23]{index=23}
  

  installではロック外のパッケージは残存しますが、syncは不要なパッケージを除去しロックファイルと一致させます。

• requirements.txtの生成 (ロックファイル作成): 既存の依存定義からロック用の requirements.txt を作成するには uv pip compile を使用します。

  $ uv pip compile pyproject.toml -o requirements.txt  # pyproject.tomlからロック生成:contentReference[oaicite:25]{index=25}
  $ uv pip compile requirements.in -o requirements.txt # requirements.inからロック生成:contentReference[oaicite:26]{index=26}
  $ uv pip compile --group dev -o requirements-dev.txt # devグループ依存だけロック生成:contentReference[oaicite:27]{index=27}
  

  -o（--output-file）オプションで出力ファイルを指定します。複数の入力ソースやエクストラ要件（--extra foo）にも対応しています。
  また、既存のロックファイルがある場合、デフォルトではピン留めされたバージョンを維持し再解決時に勝手にアップグレードしません。アップグレードしたい場合は --upgrade フラグや --upgrade-package <名> を指定します。

pyproject.tomlへの自動追記（依存関係の追加/削除）

• 依存パッケージの追加: プロジェクトに依存関係を追加するには uv add <パッケージ名> を使います。これにより pyproject.toml の [project.dependencies] フィールドに該当パッケージが追記され、かつ仮想環境にもインストールされます。

  $ uv add httpx        # httpxをdependenciesに追加しインストール:contentReference[oaicite:33]{index=33}
  

  上記実行後、pyproject.tomlの[project]セクションに "httpx>=0.27.2" といったバージョン制約付きのエントリが自動追加されます。バージョン制約は自動で付与されますが、"httpx>=0.20" のように手動で指定することも可能です。

• 開発・オプショナル依存の追加: 開発用依頼や任意のグループに追加する場合、uv add にフラグを付与します。

  • --dev フラグ: 開発用依存 (devグループ) に追加。
  • --group <名前> フラグ: カスタム依存グループに追加 (例: lintやtestなどグループ名を任意指定)。
  • --optional フラグ: 発行パッケージのオプショナル依存（エクストラ）に追加。

  例:

  $ uv add --dev pytest           # pytestを開発用依存に追加:contentReference[oaicite:37]{index=37}
  $ uv add --group lint ruff      # ruffを lint グループ依存に追加
  $ uv add --optional gui tk      # tkをオプショナル依存「gui」に追加
  

• 依存パッケージの削除: uv remove <パッケージ名> で pyproject.tomlから該当パッケージの記載を削除し、仮想環境からもアンインストールします。--dev/--group/--optionalフラグで特定セクションからの削除も可能です。

  $ uv remove httpx              # httpxをdependenciesから削除:contentReference[oaicite:40]{index=40}
  $ uv remove --dev pytest       # pytestをdev依存から削除
  

ロックファイルの生成・利用

• ロックファイル (uv.lock) の役割: uvはプロジェクト依存の正確なバージョン解決結果を uv.lock というファイルに保存します。このロックファイルはOSやPythonバージョン差異を含め全プラットフォームで再現可能な形で依存関係を記録するクロスプラットフォーム対応のファイルです。プロジェクトメンバー間やデプロイ環境で常に同一バージョンを使うため、uv.lock をバージョン管理に含めてください。

• ロックファイルの自動/手動作成: uvはプロジェクトのコマンド実行時にロックファイルを自動更新します（後述のuv run実行時など）。手動でロックファイルを生成・更新したい場合は次を実行します:

  $ uv lock   # pyproject.tomlに基づきuv.lockを生成/更新:contentReference[oaicite:45]{index=45}
  

  また、uv lock --check とすれば現在のロックファイルが最新か確認できます。自動ロックを無効化したい場合、各コマンドに --locked（ロックファイルが古い場合はエラーにする）や--frozen（ロックファイル更新をチェックしない）オプションを付ける方法もあります。

• 環境同期: 上述の通り、uv sync コマンドでプロジェクトの仮想環境を uv.lock に完全同期させることができます。リポジトリをクローンした後など、まず uv sync を実行することで .venv が作成されロックファイルに従った環境が構築されます。

• ロックファイルのエクスポート: プロジェクトのロック情報を標準的な requirements.txt 形式でエクスポートしたい場合、uv pip compileを利用してください（前述）。将来的に複数環境間で共有する場合に便利です。

グループ依存（dev, lint など）の管理

• 依存グループとは: uvでは依存関係を「公開用」と「開発用」等にグループ分けできます。[project.optional-dependencies]（エクストラ）や[tool.uv.dependency-groups]に定義し、必要に応じてインストールを切り替えられます。例えば、テストやLintなど開発時のみ必要なパッケージは「dev」グループに分類し、本番環境インストールから除外する、といった運用が可能です。

• 開発依存 (dev) の扱い: uv add --dev で追加されたパッケージは開発グループに入ります。devグループは特別扱いで、デフォルトでは同期やインストール時に含まれます。すなわち、uv sync や uv run は devグループの依存もインストールされます（本番環境等で除外したい場合は --no-dev オプションで除外可能）。

• グループ別インストール: 任意のグループのみインストールする場合、uv pip install --group <グループ名> を使用します。例えば uv pip install --group lint とすればpyproject.toml内のlintグループの依存項目だけをインストールできます。逆にすべての開発グループを無視するには uv pip install --no-default-groups とするといった制御も可能です（dev含むデフォルトグループ全て除外）。

• レガシー形式との互換: 既存プロジェクトでPoetryやpipenvのdev依存（旧tool.poetry.dev-dependencies等）を使っている場合も、uvはそれらを検知してuv add --dev時に適切に既存セクションへ追加します。

uv run の使い方

• コマンドの実行: uv run <コマンド> はプロジェクトの仮想環境内で指定したコマンドを実行します。仮想環境を手動でactivateしなくても、このコマンドを通せば環境内のPythonやツールを利用できます。実行前に依存関係のロックと同期が自動で行われ、環境が最新状態になる点も特徴です。例：

  $ uv run python app.py       # 仮想環境内のPythonで app.py を実行:contentReference[oaicite:60]{index=60}
  $ uv run pytest              # 仮想環境内にインストールしたpytestを実行
  $ uv run bash scripts/build.sh   # 仮想環境を利用してbashスクリプトを実行:contentReference[oaicite:61]{index=61}
  

• エイリアス: uv run はPoetryのpoetry runやPipenvのpipenv runに相当します。これにより .venv をactivateすることなく常に最新環境でコマンドを実行できます。

• 追加依存付きでの実行: 一時的に別バージョンのパッケージで試したい場合など、--with オプションでその実行時だけ特定の依存バージョンを指定できます。例えば:

  $ uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)":contentReference[oaicite:64]{index=64}
  

  こうするとプロジェクトが要求するバージョンに関わらず、一時的に httpx 0.26.0 を使ってコマンドを実行できます。

よくあるトラブルと解決法

• UnicodeDecodeError が発生する場合: Windows環境などでパッケージインストール時に UnicodeDecodeError: 'charmap' codec can't decode byte ... のようなエラーが出ることがあります。これはセットアップスクリプトや設定ファイルの読み込みで、デフォルトの文字エンコーディングが原因となる場合があります。対処方法として、以下を試してください:

  • UTF-8モードの有効化: コマンド実行時に環境変数 PYTHONUTF8=1 を設定し、PythonのUTF-8モードを有効にします（Windowsのデフォルトcp1252をUTF-8に強制する）。
  • エンコーディング指定: 該当エラーが発生するファイルを特定できれば、ファイルのエンコーディングをUTF-8に変換するか、読み込み時にencoding='utf-8'を指定するようスクリプトを修正します。
  • 依存バージョンの変更: 特定バージョンのパッケージで問題が起きる場合、別バージョンへダウングレード/アップグレードする（例ではkokoro-onnx 0.4.6で発生し0.4.5で回避）。

• 「仮想環境が見つからない」エラー: uv pip install など実行時に仮想環境が無いとエラーやプロンプトが表示されます。その際は uv venv を実行して仮想環境を作成してください。また、CIなどシステム環境に直接インストールしたい場合は uv pip install --system ... フラグで仮想環境をスキップしてシステムにインストール可能です。ただし通常は仮想環境の利用が推奨されます。

• ビルドエラーが起きた場合: C拡張のビルド失敗など uv 特有でないエラーもあります。uvは基本的にpipと同じエラーを出力します。コンパイルエラー時は必要なビルドツールのインストールや、--no-build-isolation オプションの使用（既存環境のビルド依存を使う）など、通常のPythonパッケージの対処法が有効です。エラーメッセージ内のヒントや公式ドキュメントの「Troubleshooting」セクションも参照してください。