Zenn
Closed7

uv 0.3.0 チートシート

Python
uv
ピン留めされたアイテム
まちゅけんまちゅけん

uv 0.3.0 がリリースされました。

https://astral.sh/blog/uv-unified-python-packaging

このリリースでは End-to-end project management な機能等が追加されています。これまでは pip や pip-tools のドロップインが売りだった uv ですが、遂に rye の範囲をカバーするような存在となってきました。 このスクラップでは 0.3.0 の新機能をチートシート的にまとめてみます。

まちゅけんまちゅけん

インタプリタ

uv で Python インタプリタを管理できるようになりました。 Rye や Hatch などにもある最近流行りの機能ですね。 もはや Python のインストールを気にする必要がありません。

uv run や uv sync などのコマンドを実行する際、必要があれば自動で Python をインストールしてくれます。

Python バージョンをピン留めする

$ uv python pin 3.12
Pinned `.python-version` to `3.12`

インタプリタを一覧する

$ uv python list
cpython-3.12.5-linux-x86_64-gnu     <download available>
cpython-3.11.9-linux-x86_64-gnu     <download available>
cpython-3.10.14-linux-x86_64-gnu    <download available>
cpython-3.9.19-linux-x86_64-gnu     <download available>
cpython-3.8.19-linux-x86_64-gnu     <download available>
pypy-3.7.13-linux-x86_64-gnu        <download available>

インタプリタをインストールする (手動)

$ uv python install 3.12
Searching for Python versions matching: Python 3.12
Installed Python 3.12.5 in 2.50s
 + cpython-3.12.5-linux-x86_64-gnu
まちゅけんまちゅけん

スクリプト

uv run コマンドが追加されました。 いちいち仮想環境を気にせずにスクリプトを実行できます。

スクリプトの例:

main.py
import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

上記のスクリプトは requests と rich に依存しているので、通常は仮想環境を作ってインストールしないと ModuleNotFoundError が発生します。 以下の機能を使うことで仮想環境を作成するより少ない作業でスクリプトを実行できます。

依存関係を指定して実行する

uv run コマンドと --with オプションでパッケージ名を指定します。

$ uv run --with "requests<3" --with rich main.py
Installed 9 packages in 12ms
[
│   ('1', 'PEP Purpose and Guidelines'),
│   ('2', 'Procedure for Adding New Modules'),
│   ('3', 'Guidelines for Handling Bug Reports'),
│   ('4', 'Deprecation of Standard Modules'),
│   ('5', 'Guidelines for Language Evolution'),
│   ('6', 'Bug Fix Releases'),
│   ('7', 'Style Guide for C Code'),
│   ('8', 'Style Guide for Python Code'),
│   ('9', 'Sample Plaintext PEP Template'),
│   ('10', 'Voting Guidelines')
]

インライン依存関係を追加する (PEP 723)

なんと PEP 723 のインライン依存関係を編集する機能が追加されました。 編集機能は見たことがありません。 まるで pyproject.toml に依存関係を追加するかのような機能です。

uv add コマンドと --script オプションを使います。

$ uv add --script main.py "requests<3" "rich"
Updated `main.py`

main.py ファイルが以下のように編集されます。

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "requests<3",
#     "rich",
# ]
# ///
import requests
from rich.pretty import pprint

resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])

インライン依存関係で実行する (PEP 723)

上記のように PEP 723 仕様を付けたファイルは uv run コマンドのオプションなしで実行できます。実行については pipx run のような機能です。

$ uv run main.py
Installed 9 packages in 12ms
[
│   ('1', 'PEP Purpose and Guidelines'),
│   ('2', 'Procedure for Adding New Modules'),
│   ('3', 'Guidelines for Handling Bug Reports'),
│   ('4', 'Deprecation of Standard Modules'),
│   ('5', 'Guidelines for Language Evolution'),
│   ('6', 'Bug Fix Releases'),
│   ('7', 'Style Guide for C Code'),
│   ('8', 'Style Guide for Python Code'),
│   ('9', 'Sample Plaintext PEP Template'),
│   ('10', 'Voting Guidelines')
]
まちゅけんまちゅけん

プロジェクト

プロジェクト管理のワークフローを実行できます。 Rye, Hatch, PDM, Poetry などのツールのように機能します。

プロジェクトを作成する (新しいディレクトリ)

$ uv init hello-world
Initialized project `hello-world` at `/tmp/tmp.EFm5ITAaNg/hello-world`

プロジェクトを初期化する (現在のディレクトリ)

$ uv init
Initialized project `hello-world`

依存関係を追加する

pyproject.toml を編集するコマンド群です。 さらに仮想環境の作成と依存関係をインストール、ロックファイルを生成をしてくれます。

依存関係 (project.dependencies)

$ uv add httpx
Using Python 3.12.5
Creating virtualenv at: .venv
Resolved 8 packages in 234ms
   Built example @ file:///tmp/tmp.iziGJMqakY/example
Prepared 8 packages in 428ms
Installed 8 packages in 6ms
 + anyio==4.4.0
 + certifi==2024.7.4
 + example==0.1.0 (from file:///tmp/tmp.iziGJMqakY/example)
 + h11==0.14.0
 + httpcore==1.0.5
 + httpx==0.27.0
 + idna==3.7
 + sniffio==1.3.1
pyproject.toml
[project]
dependencies = [
    "httpx>=0.27.0",
]

オプション依存関係 (project.optional-dependencies)

uv add httpx --optional network
Resolved 8 packages in 16ms
   Built example @ file:///tmp/tmp.iziGJMqakY/example
Prepared 1 package in 239ms
Uninstalled 1 package in 0.67ms
Installed 1 package in 1ms
 ~ example==0.1.0 (from file:///tmp/tmp.iziGJMqakY/example)
pyproject.toml
[project.optional-dependencies]
network = [
    "httpx>=0.27.0",
]

開発依存関係

$ uv add ruff --dev
Resolved 9 packages in 216ms
   Built example @ file:///tmp/tmp.iziGJMqakY/example
Prepared 2 packages in 467ms
Uninstalled 1 package in 0.48ms
Installed 2 packages in 2ms
 ~ example==0.1.0 (from file:///tmp/tmp.iziGJMqakY/example)
 + ruff==0.6.1
pyproject.toml
[tool.uv]
dev-dependencies = [
    "ruff>=0.6.1",
]
まちゅけんまちゅけん

依存関係を同期する

従来のコマンドですが uv sync でプロジェクトを依存関係をインストールします。 既存の uv プロジェクトを git clone した際など仮想環境が存在しない場合に利用できます。 もちろんロックファイルを参照し、Python もなけばインストールしてくれます。

$ uv sync
まちゅけんまちゅけん

ツール

uvx 及び uv tool コマンド群で Python 製のコマンドラインツールを分離された環境にインストール、実行できます。 pipx のドロップインのようですね。

一度のみの実行

$ uvx pycowsay hello from uv
Installed 1 package in 3ms

  -------------
< hello from uv >
  -------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

ユーザー環境にインストール

$ uv tool install ruff
Resolved 1 package in 149ms
Prepared 1 package in 397ms
Installed 1 package in 1ms
 + ruff==0.6.1
Installed 1 executable: ruff

$ ruff --version
ruff 0.6.1

ツール一覧

$ uv tool list
ruff v0.6.1
- ruff

一括アップデート

$ uv tool upgrade --all
Nothing to upgrade

一括アンインストール

$ uv tool uninstall --all
Uninstalled 1 executable: ruff
まちゅけんまちゅけん

シェル補完

bash
$ mkdir --parents ~/.local/share/bash-completion/completions
$ uv generate-shell-completion bash > ~/.local/share/bash-completion/completions/uv.bash

公式ドキュメント

https://docs.astral.sh/uv/

このスクラップは3ヶ月前にクローズされました