寝て起きたら忘れているuvを記録する。(Geminiを利用して執筆してます)

はじめに

Pythonには Anaconda や pip を始めとしたさまざまなパッケージ管理ツールが存在します。そのなかでも、最近デファクトスタンダードになりつつあるのが uv です。
本記事では uv の基本的なコマンドをまとめたのち、実際の使用例を紹介します。

実際の使用例は、自分が研究でuvを用いるときの手順です。我流な点もあるかもしれないのでご了承ください。「これが正攻法だよ」といったコメントも大歓迎です！

そもそもuvってな～に？

uv は、2024年にAstral社からリリースされた、Rust製のPythonパッケージ・プロジェクト管理ツールです。近年では Hugging Face のモデルカードや Gemini のデモ等々、パッケージ管理のツールとして先ずは uv が使われている印象です。

最大の強みは圧倒的な実行速度です。公式ドキュメントによると、従来の pip や pip-tools と比較して10〜100倍速いのだそう。

公式ドキュメント

また、uv はパッケージ間の依存関係を高速に解消し、競合しないようにパッケージの追加を進めてくれます（厳密すぎて逆に不便になときもあったり）

さらに、普通はプロジェクト実行の前に手動で環境の activate をする必要がありますが、uv はファイル実行時に実行位置から環境を自動で判断し、自動で activate して実行してくれる特徴があります。

activateとは？

パッケージ管理をする際、インストールしたパッケージは特定のディレクトリ（仮想環境）に保存されます。複数の環境がある中で、いま使う環境をPCへ指定する操作が activate です。
逆に、指定を解除するのにはdeactivateを使用します。

uvの使いかた

コマンド早見表

仮想環境の管理

コマンド	役割
`uv init`	プロジェクトの新規作成
`uv venv`	仮想環境（.venv）の新規作成
`uv run`	パッケージを考慮した上でのPythonファイルの実行
`uv add`	パッケージの追加（pyproject.tomlに記録される）
`uv remove`	パッケージの削除
`uv sync`	記録された依存関係（uv.lock）をもとに環境を同期
`uv lock`	依存関係を計算し、uv.lockファイルを更新

uv python 系（Python自体のバージョン管理のためのコマンド）

コマンド	役割
`uv python install`	指定したバージョンのPythonをダウンロード・インストール（例: `uv python install 3.12`）
`uv python pin`	現在のプロジェクトで使用するPythonバージョンを固定（`.python-version` が更新される）
`uv python list`	インストール済み・利用可能なPythonのバージョン一覧を表示

uv pip 系（従来のpipと互換性のあるコマンド）

コマンド	役割
`uv pip install`	仮想環境に直接パッケージをインストール
`uv pip list`	インストール済みのパッケージ一覧を表示
`uv pip show`	特定のパッケージの詳細を表示

主要コマンドの解説

`uv init`

uvのプロジェクトを新規で作成するコマンドです。
uv-0.12.12では 「アプリケーション」 と 「ライブラリ」 の２つの基本テンプレートをサポートしており、デフォルトはアプリケーションです。

このコマンドによって、以下のような構成が作成されます。

$ uv init <project-name> #`<project-name>`には任意のプロジェクト名を指定します。

# project-nameのようにハイフン(-)を含む場合、
# 自動でアンダースコア(_)に正規化されるらしい

$ tree project_name
project_name/
├── .python-version  # 使用するPythonのバージョンが記載される
├── README.md        # プロジェクトの説明
├── pyproject.toml   # パッケージやプロジェクトの設定ファイル
└── src
    └── project_name
        └── __init__.py #__init__.pyについてはツリーの記事を参照してください

__init__.pyそのものにも役割はありますが、今回は割愛します。詳しくはこちら¹
このとき、pyproject.tomlには以下は以下のような構成になります。

[project]
name = "project_name"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[project.scripts]
example-app = "project_name:main"

[build-system]
requires = ["uv_build>=0.12.12,<0.13"]
build-backend = "uv_build"

上記はアプリケーションの場合です。

ライブラリモード（--lib）では、型情報のサポートを示すマーカーファイルである py.typed²が生成されます。これにより、パッケージ配布時に利用側の型チェッカー（mypyなど）が型定義を正しく認識できるようになります。ライブラリモードについては割愛。（よく知らない）

ふらっと登場したpyproject.tomlはパッケージの依存関係を記録するファイルで、uvは後述するuv addやuv remove時に本ファイルを参照したり、自動で編集したりします。ケースによりけり、自分でpyproject.tomlに書き込むこともあります。

uv initをした時点では仮想環境は作成されません。

`uv venv`

現在のディレクトリに仮想環境（デフォルトでは .venv フォルダ）を作成します。ただし、uvは uv run や uv add を実行した際に、仮想環境がなければ自動で作成してくれるため、明示的にコマンドを叩く必要はないです。

`uv add`

プロジェクトにパッケージを追加します。後述する pyproject.toml に依存関係として自動で書き込まれ、同時にインストールも行われます。
特定のバージョンを指定して追加したい場合は、以下のように記述します。

uv add "numpy==1.26.4"
uv add "pandas>=2.0.0"

また、（個人的に）よく使う印象のオプションとして

--index
--no-build-isolation

について紹介します。

--index
PyPI 以外のパッケージ配布元からaddしたいとき、インデックス URLを指定するためのオプションです。
【例: GPU版 PyTorch のインストール】
PyTorch の CUDA 版は通常の PyPI ではなく専用サーバーで wheel が配布されているため、URL を明示する必要があります。

#cuda12.4バージョンのtorchをインストールしたい場合
uv add torch torchvision torchaudio --index https://download.pytorch.org/whl/cu124

--no-build-isolation
パッケージのビルド時にクリーンな一時環境を作らず、現在の仮想環境にインストールされているライブラリを使ってビルドします。

【例: flash-attn のインストール】
C++/CUDA 拡張のコンパイルを伴う flash-attn は、ビルド時に環境内の torch や CUDA ツールチェーンを直接参照する必要があります。通常の隔離ビルドだと一時環境側に torch が存在せずエラーになるため、このフラグで既存環境を参照させます。

uv add flash-attn --no-build-isolation

導入にひと癖あるパッケージは、こうしたオプションを渡しながらインストールします。

`uv run`

構築した仮想環境を用いて、Pythonスクリプトを実行します。先述の通りuvが自動で実行環境を探すため、手動での activate は不要です。

通常のpythonコマンドと同様に、スクリプトに引数を渡したい場合は

uv run script.py arg1 arg2

のようにそのまま後ろに続けて記述するだけでOKです。

uvの使用例

本章では、uvまわりのユースケースをいくつかご紹介します。記事冒頭でお伝えの通り、我流な部分もあるかと思いますのでご了承ください。追記するかもしないかも。

1. プロジェクトを新規でつくる場合

# 1. プロジェクトの作成
$ uv init my_project
$ cd my_project
$ uv python pin 3.10 #pythonのバージョンを固定する

# 2. 必要なパッケージの追加（仮想環境が作られていない場合、始めに仮想環境が作られます）
$ uv add numpy pandas sl

# 3. なにかしら作成したプロジェクトの実行
$ uv run src/hello.py

#間違えてパッケージを追加しちゃって、消したいとき
$ uv remove sl

sl?

$ sl





                          (  ) (@@) ( )  (@)  ()    @@    O     @     O     @      O
                     (@@@)
                 (    )
              (@@@@)

            (   )
         ====        ________                ___________
     _D _|  |_______/        \__I_I_____===__|_________|
      |(_)---  |   H\________/ |   |        =|___ ___|      _________________
      /     |  |   H  |  |     |   |         ||_| |_||     _|                \_____A
     |      |  |   H  |__--------------------| [___] |   =|                        |
     | ________|___H__/__|_____/[][]~\_______|       |   -|                        |
     |/ |   |-----------I_____I [][] []  D   |=======|____|________________________|_
   __/ =| o |=-O=====O=====O=====O \ ____Y___________|__|__________________________|_
    |/-=|___|=    ||    ||    ||    |_____/~\___/          |_D__D__D_|  |_D__D__D_|
     \_/      \__/  \__/  \__/  \__/      \_/               \_/   \_/    \_/   \_/

2. uvで環境構築されたGitリポジトリをクローンする場合

# 1. gitからリポジトリをクローン(リポジトリにuv関係のファイルが入っている想定です)
$ git clone https://github.com/example/example_rp.git
$ cd example_rp

# 2. パッケージの一括追加と環境構築
# （リポジトリ内にある pyproject.toml や uv.lock を読み込んで環境を同期）
$ uv sync

# 3. 実行
$ uv run script.py

おわりに

本記事では、デファクトスタンダードになりつつある uv の使い方や、実践的な具体例を紹介しました。

高速で快適なパッケージ管理は、開発や研究のストレスを大きく減らしてくれます。どなたかの参考になれば幸いですし、誤りや「もっといい使い方があるよ！」という点があれば、ぜひコメントでご指摘いただけるとありがたいです。

よき研究ライフを！