⚡

Pythonのパッケージ管理ツール「uv」の使い方

2025/02/13に公開

Python

Ruff

tech

1. プロジェクトの初期化

プロジェクトの初期化

新しいプロジェクトを作成するには、以下のコマンドを使用する。
```
uv init プロジェクト名
```
このコマンドにより、pyproject.toml ファイルが生成され、プロジェクトの基本構成が整う。
さらに、--app オプションでアプリケーションプロジェクト、--lib オプションでライブラリプロジェクトを作成できる。

例えば
```
uv init --app my-app
uv init --lib my-lib
```

2. 仮想環境の作成、入り方、出方

uvはプロジェクトごとに仮想環境を自動的に作成・管理する。手動で仮想環境を作成する場合は、以下のコマンドを使用する。

uv venv

仮想環境に入るには、以下のコマンドを実行する。

source .venv/bin/activate

仮想環境から出るには、以下のコマンドを使用する。

deactivate

3. パッケージの追加、requirements.txt のようなプロジェクトで使うパッケージの一括管理

依存関係の追加や削除は以下のコマンドで行う。

パッケージの追加

uv add パッケージ名

開発用依存関係の追加

uv add --dev パッケージ名

パッケージの削除

uv remove パッケージ名

uvは pyproject.tomlファイルで依存関係を管理し、uv.lockファイルでロックする。
これにより、requirements.txtのような一括管理が可能となる。

4. その他開発で使う場合のコマンド

スクリプトの実行

uv run スクリプト名.py

依存関係の同期

uv sync

ロックファイルの更新

uv lock

Pythonバージョンの指定

uv python pin バージョン番号

仮想環境の手動アクティベート（必要な場合）

source .venv/bin/activate

仮想環境からの退出は以下のコマンドで行う。

deactivate

ただし、uv は仮想環境の管理を自動化しているため、通常は手動でのアクティベートやデアクティベートは不要である。

5. ワークスペースの活用

uvはCargoスタイルのワークスペースをサポートしており、複数のパッケージをまとめて管理できる。
ワークスペースを設定するには、pyproject.tomlファイルに [tool.uv.workspace] テーブルを追加し、membersキーでワークスペースに含めるパッケージを指定する。
例えば、以下のように設定する。

[tool.uv.workspace]
members = ["package1", "package2", "subdir/package3"]

この設定により、uvは指定されたメンバーを一つのワークスペースとして扱い、依存関係の管理やビルドを統合的に行う。

6. 依存関係の解決

uvは高度な依存関係解決アルゴリズムを備えており、バージョン制約、プラットフォームマーカー、依存関係の競合などを考慮して最適なパッケージの組み合わせを探索する。
依存関係の解決とインストールは以下のコマンドで行う。

uv sync

uv syncは pyproject.tomlとuv.lockを基に、依存関係を解決し、必要なパッケージをインストールする。
特定の環境向けに依存関係を解決する場合、--targetオプションでターゲットプラットフォームを指定できる。

uv sync --target x86_64-unknown-linux-gnu

7. キャッシュの管理

uvは強力なキャッシュ機構を備えており、ダウンロードしたパッケージやビルドされたwheelファイル、ソースコードなどをキャッシュすることで、依存関係の解決とインストールを高速化する。
キャッシュの管理には以下のコマンドを使用する。

キャッシュのクリア（全削除）
```
uv cache clean
```
特定のパッケージのキャッシュを削除:
```
uv cache clean パッケージ名
```
未使用キャッシュの削除（プルーニング）
```
uv cache prune
```
CI/CD向けに未使用ビルドデータのみを削除:
```
uv cache prune --ci
```

8. ビルドの分離

uvは、PEP 517とPEP 660に準拠したビルドの分離をサポートしており、各パッケージを隔離された環境でビルドすることで、依存関係の競合を防ぎ、ビルドの再現性を向上させる。
ビルドの分離はデフォルトで有効になっており、特別な設定やコマンドは不要である。

9. パブリッシュ

uvは、Pythonパッケージをビルドし、レジストリにアップロードする機能を提供する。
以下のコマンドでソースディストリビューションとバイナリディストリビューションをビルドする。

uv build

ビルド後、パッケージをレジストリにアップロードするには、以下のコマンドを使用する。

uv publish

uv publishコマンドでは、認証情報を指定するために以下のオプションを使用できる。

PyPIトークンを指定

uv publish --token YOUR_PYPI_TOKEN

ユーザー名とパスワードを指定

uv publish --username YOUR_USERNAME --password YOUR_PASSWORD

10. 他ツールとの連携

Dockerとの連携
uvは公式のDockerイメージを提供しており、これを利用することで、コンテナ内でuvを簡単に実行できる。
例えば、以下のようなDockerfileを作成する。
```
FROM astralapp/uv:latest

WORKDIR /app
COPY . /app

RUN uv sync
CMD ["uv", "run", "your_script.py"]
```
GitHub Actionsとの連携
GitHub Actionsでuvを使用するには、公式のastral-sh/setup-uvアクションを利用するのが便利である。
.github/workflows/ディレクトリに以下のようなワークフローファイルを作成する。
```
name: CI

on: [push, pull_request]

jobs:
build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: astral-sh/setup-uv@v1
    - run: uv sync
    - run: uv run your_script.py
```
GitLab CI/CDとの連携
GitLab CI/CDでも、uvの公式Dockerイメージを利用できる。
.gitlab-ci.ymlファイルに以下のように記述する。
```
image: astralapp/uv:latest

stages:
- build

build:
stage: build
script:
    - uv sync
    - uv run your_script.py
```

以上が、uvの高度な機能と各機能に関連する詳細なコマンドラインオプションである。