uv （pythonパッケージマネージャー）の使い方　簡易版

[**詳細版はこちら**](https://qiita.com/futakuchi0117/items/c913c64823724f3f9851)

読者が **uv**をシステム開発にすぐに応用できることを目指します。

- [uv公式ドキュメント](https://docs.astral.sh/uv/)
- [uv (github)](https://github.com/astral-sh/uv)

# -1. なぜ `uv` なのか

- 名前の由来は `UniVerse` （宇宙！） とか `UltraViolet` （紫外線）とかっぽいんですが、実際のところ何が由来なのかわかりませんでした（[参照](https://lwn.net/Articles/986663/)）
- `pip`, `pip-tools`, `pipx`, `poetry`, `pyenv`, `twine`, `virtualenv` といった従来のパッケージマネージャーを置き換えることができる！
- [公式](https://docs.astral.sh/uv/)曰く、`extremely fast` なパッケージマネージャーということで、 `pip` の 10 ～ 100 倍高速だそうです。`poetry` よりも15倍くらい早い！これは使うしかありませんね？

![Monosnap uv 2024-11-01 23-53-30.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/193401/5d723ca3-3b64-dac3-55e5-03dffdbb45a1.png)


# 0. uvの基本的な使い方 (インストール済みという前提で)

uvの使い方は超簡単です。以下は、最も基本的な使い方の流れです。

**新規プロジェクトの作成**

```bash
uv init my-ml-project
```

**依存関係の追加**

```bash
uv add scikit-learn pandas matplotlib
```

**スクリプトの実行**

```bash
uv run my_ml_script.py
```

## 0.1. 使用感は poetry に似ているが、uvのメリットは大きい

uvの `uv init`, `uv add`, `uv run` という基本的なコマンドの流れは **poetry** に似ています。

poetryも、`poetry new`, `poetry add`, `poetry run` というコマンドで、プロジェクトの作成、依存関係の追加、スクリプトの実行を行います。

poetryは、依存関係の管理、仮想環境の管理、build、publish など、Pythonパッケージの開発に必要な機能を包括的に持っており、uvも同様の機能を備えています。

ただし、uvはpoetryよりも高速な動作、クロスプラットフォーム対応のロックファイル（素晴らしい...）、ワークスペースによる複数パッケージの管理など、いくつかの点で優位性があるそうです。

（poetry は linux系と windows でlockファイルの互換性が全然なかったりしましたがuvはどうなんでしょうね？未調査です）

uvは `uv pip` コマンドで、pip互換のインターフェースを提供しており、pipに慣れたユーザーはスムーズに移行することができます。

一方、poetryは豊富なドキュメント、活発なコミュニティなど成熟したパッケージマネージャーであり、安定性があります。

最終的にどちらのパッケージマネージャーが適しているかはいまのところ開発チームの好みでいい気がします。


# 1. uvのインストールとセットアップ

uvは、以下の方法でインストールできます。

- 公式インストーラー (推奨)

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

- pip

```bash
pip install uv
```

- Homebrew (macOS)

```bash
brew install uv
```

- Cargo

```bash
cargo install --git https://github.com/astral-sh/uv uv
```

インストール後、`uv generate-shell-completion` を実行してシェルに自動補完機能を追加することをお勧めします。

# 2. uvの基本的な使い方

uvのコマンド体系はシンプルで、直感的に操作できます。

- `uv add`: 依存関係を追加
- `uv remove`: 依存関係を削除
- `uv sync`: 環境を最新の状態に同期
- `uv run`: スクリプトを実行
- `uv lock`: ロックファイルを更新

# 3. uvによるプロジェクト管理

uvは、`pyproject.toml` で定義されたPythonプロジェクトを管理できます。

- `uv init`: 新規プロジェクトを作成
- `uv add`: 依存関係を追加
- `uv remove`: 依存関係を削除
- `uv sync`: 仮想環境を更新

**プロジェクトの例**

```toml
[project]
name = "my-ml-project"
version = "0.1.0"
requires-python = ">=3.8"
dependencies = [
    "scikit-learn",
    "pandas",
    "matplotlib",
]

[tool.uv.sources]
# 必要に応じて、Gitリポジトリやローカルパスなど、
# さまざまなソースからの依存関係を指定できます。
```

# 4. Dockerとの連携

uvはDockerとの連携が容易で、コンテナ化された機械学習アプリケーションの開発を効率化します。

**Dockerfileの例**

```dockerfile
FROM python:3.9-slim

# uvをインストール
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# プロジェクトをコピー
COPY . /app
WORKDIR /app

# 依存関係をインストール
RUN uv sync --frozen

# アプリケーションを実行
CMD ["uv", "run", "main.py"]
```

# 5. GitHub Actionsとの連携

uvは、GitHub Actionsと連携して、CI/CDパイプラインに統合できます。

**workflowの例**

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install uv
        uses: astral-sh/setup-uv@v3
      - name: Install dependencies
        run: uv sync --dev
      - name: Run tests
        run: uv run pytest
```

# 6. Jupyterとの連携

uvは、Jupyter Notebookと連携して、インタラクティブな機械学習開発をサポートします。

**Jupyter Notebookでの使用例**

```bash
# Jupyter Labを起動
uv run --with jupyter jupyter lab

# Notebook内でパッケージをインストール
!uv add pydantic
```

# 7. poetry, venv, pipからの移行

既存のpoetry, venv, pipプロジェクトをuvに移行するのは簡単です。

**poetryからの移行**

1. `pyproject.toml` をuvの形式に変換します。
2. `poetry export -f requirements.txt --output requirements.txt` で依存関係をエクスポートします。
3. `uv pip install -r requirements.txt` でuv環境に依存関係をインストールします。

**venv, pipからの移行**

1. `pip freeze > requirements.txt` で依存関係をエクスポートします。
2. `uv venv` で新しい仮想環境を作成します。
3. `uv pip install -r requirements.txt` で依存関係をインストールします。

# 参照

- [uv公式ドキュメント](https://docs.astral.sh/uv/)
- [uv (github)](https://github.com/astral-sh/uv)