Zenn
🌅

初めてのuv入門｜uvコマンドガイド：uv Scripts編

に公開
Python
uv
tech

知識は武器とかけまして、レゴブロックと解く、その心は――
今日もKnowledge Oasisへようこそ
案内人はkoふみです
本日のテーマは『uv コマンドガイド』

はじめに

Python のプロジェクト管理や環境切り替えって、意外と手間がかかりますよね。特に複数バージョンを切り替えたいときや、一時的に依存パッケージを解決したいときなど、仮想環境を作ったり消したりするのが面倒です。
そこで今回は、uv コマンド（uv run、uv add、uv remove）を使って、Python 環境をまるでオアシスのように手軽に扱う方法をご紹介します。依存解決やプロジェクト単位の管理を、まるで泉から水を汲むかのようにサクッと行える感覚を味わってみましょう。

対象読者

  • Python プロジェクトを複数バージョンで管理したいエンジニアや開発者
  • プロジェクトに依存パッケージを追加・削除したいが、手動で環境をいじるのが面倒なあなた
  • uv コマンドを使ったことはないが、仮想環境の自動化に興味がある方

――では、さっそく各コマンドの使い方を見ていきましょう。

uv run: Python スクリプトやコマンドを実行

概要

uv run は、任意の Python スクリプトやコマンドを「適切な Python 環境内で」実行するためのコマンドです。スクリプトを渡すと、自動的にプロジェクトごとの仮想環境を切り替えたり、必要ならパッケージをインストールしたりして実行します。

使い方

uv run [オプション] <スクリプトパスまたは '-'>
  • example.py を指定すると、uv run python example.py と同様に動作します。
  • URL を指定すると、自動でダウンロードして実行します。
  • - を指定すると、標準入力からスクリプトを読み込みます。

例

uv run example.py
uv run --no-project example.py
echo 'print("hello world!")' | uv run -

主なオプション

  • --no-project

    • 説明：カレントディレクトリ以下の pyproject.toml を無視して、スクリプト単体だけを実行したいときに使う。
    • 使いどころ：プロジェクト依存を一切取り込まずに、手早くスクリプトだけを動かしたいとき。
    • 注意：--no-project は必ずスクリプト名より前に置きます。

  • --with <パッケージ>

    • 説明：スクリプト実行前に必要な外部パッケージを明示的にインストールしてから実行する。
    • 使いどころ：「この一度だけ動かすスクリプトに必要な依存」をその場で解決したいとき。
    • 例：uv run --with requests --with rich example.py

  • --python <バージョン>

    • 説明：指定した Python バージョンでスクリプトを実行する。
    • 使いどころ：「必ず Python 3.10 で動かしたい」といったケース。
    • 例：uv run --python 3.10 example.py

  • - （スクリプトを標準入力から読む）

    • 説明：stdin から直接スクリプト本体を読み込んで実行する。

    • 使いどころ：一時的なスクリプトをファイルに保存せず、そのまま実行したいとき。

    • 例：

      echo 'print("hello world!")' | uv run -
uv run - <<EOF
print("hello world!")
EOF

  • --script

    • 説明：スクリプトファイル先頭に記述した inline metadata（依存や Python バージョン指定など）を使って実行する。
    • 使いどころ：# /// script セクションで依存とバージョンを明記し、プロジェクト外でもスクリプト単体で完結させたいとき。
    • 備考：# /// script があれば、--no-project を付けなくてもプロジェクト依存を無視してスクリプト依存のみを解決する。

ポイント

  • プロジェクト有無による切り替え

    • カレントディレクトリや親階層に pyproject.toml があれば、そこを「プロジェクト」とみなして依存をインストール後に実行。
    • --no-project を付けないと、意図せずプロジェクト依存が組み込まれることがあるので、スクリプト単体で動かしたいときは注意。

  • 仮想環境自動検出

    • プロジェクト外で実行するとき、カレントディレクトリや親階層に .venv があれば自動でその環境を利用。
    • 見つからなければ、PATH 上の Python を使うため、意図しないバージョンで動くことがあるので事前確認を。

  • 依存のオンデマンドインストール

    • --with で指定した依存は、スクリプト実行前に自動でインストールされる。
    • ただしプロジェクト内で実行するときは、既存のプロジェクト依存に加えて解決するため、バージョン競合に注意が必要。

uv add: 依存関係を追加

概要

uv add は、カレントディレクトリまたはその親階層にあるプロジェクト（pyproject.toml）に新しい依存パッケージを追加し、ロックファイル（uv.lock）と仮想環境を更新して実際にインストールするコマンドです。プロジェクト管理を「泉」から汲むかのように、依存がサッと追加されていきます。

使い方

uv add [オプション] <パッケージ名[<バージョン指定>]>
  • 例：uv add requests、uv add 'rich>12,<13'
  • プロジェクトが見つからない場合はエラーで終了します。

主なオプション

  • --frozen

    • 説明：ロックファイルの更新と依存チェックをスキップして、pyproject.toml にだけパッケージ名を追記する。
    • 使いどころ：CI などで「ローカル環境に影響を与えずに toml だけ変更したい」場面。
    • 例：uv add --frozen requests

  • --no-sync

    • 説明：pyproject.toml と uv.lock のみを更新し、仮想環境への実際のインストールは行わない。
    • 使いどころ：依存管理だけ設定しておき、後でまとめてインストールしたいとき。
    • 例：uv add --no-sync pandas

  • --index <URL>

    • 説明：依存解決に使うパッケージインデックスをカスタム URL に切り替える。

    • 使いどころ：社内ミラーなど独自のリポジトリを使いたい場合。

    • 例：

      uv add --index "https://internal.example/simple" requests

ポイント

  • 依存の追加とロック反映の流れ

    1. pyproject.toml の依存欄に指定したパッケージが追記される。
    2. uv.lock が自動生成され、バージョンが固定される。
    3. 仮想環境に実際に pip install が走り、すぐに使えるようになる。

  • エラー処理

    • 依存名が存在しない、あるいは互換性がない場合はエラーとなる。
    • --frozen を使うと、存在チェックをせず toml のみを更新できるため、CI/CD でロック更新を避けたいときに重宝する。

  • プロジェクトが見つからないと失敗

    • カレントや親ディレクトリに pyproject.toml がないと、エラー終了となるため、実行前に場所を確認しておくと安心。

uv remove: 依存関係を削除

概要

uv remove は、プロジェクト（pyproject.toml）から指定した依存パッケージを削除し、ロックファイル（uv.lock）と仮想環境からも該当パッケージを取り除くコマンドです。まるで不要な石を取り除くかのように、環境をクリーンに保てます。

使い方

uv remove [オプション] <パッケージ名>
  • 例：uv remove numpy
  • 指定したパッケージが存在しない場合はエラー終了します。

主なオプション

  • --frozen

    • 説明：ロックファイルの再生成をスキップし、pyproject.toml からだけ依存を除去する。仮想環境側の変更は後回しにできる。
    • 使いどころ：「まずは toml だけ整理しておきたいが、環境は一旦手を付けたくない」場合。
    • 例：uv remove --frozen numpy

  • --no-sync

    • 説明：uv.lock を更新するだけで、仮想環境からのアンインストールは行わない。
    • 使いどころ：ロックファイルを整理しておき、実際のアンインストールは後で手動で行いたいとき。
    • 例：uv remove --no-sync pandas

ポイント

  • 依存の削除とロック反映の流れ

    1. pyproject.toml の [project.dependencies] から指定パッケージをすべて取り除く。
    2. uv.lock を再生成し、依存グラフを再計算して必要なバージョンを固定し直す。
    3. 仮想環境から当該パッケージをアンインストールし、クリーンな状態に戻す。

  • 注意点

    • 条件付きマーカー（環境マーカーなど）で複数エントリがある場合も、一致するすべての行を削除する。
    • プロジェクト外で uv remove を実行すると、エラーになるので、必ず pyproject.toml のある場所で実行する。
    • --frozen、--no-sync などを使い分けて、環境と toml の変更タイミングをコントロールできるため、CI/CD や開発フローに合わせて柔軟に使おう。

まとめ

今回は、Python プロジェクトを泉のように扱える uv コマンドの中でも、特に「uv run」「uv add」「uv remove」の3つを取り上げました。

  • uv run では、スクリプト実行に最適な Python 環境を自動で用意し、依存もオンデマンドでインストール可能。
  • uv add では、プロジェクトに依存パッケージを手軽に追加し、ロックファイルと仮想環境を一気に更新。
  • uv remove では、不要なパッケージをプロジェクトからきれいに削除し、環境をクリーンに保つことができます。

これらをうまく組み合わせれば、まるで砂漠に現れたオアシスのように、Python の環境管理がスムーズになりますよ。ぜひ、あなたの開発環境でも試してみてくださいね。

知識のひとつひとつは小さなレゴブロック
でも、組み合わせれば世界を変えるアイディアをカタチにする武器になる！

またKnowledge Oasisでお会いしましょう
案内人はkoふみでした

Discussion