Zenn
Open8

uv 覚書

えんぶんえんぶん

Ryeからの移行(Windows)

latest = v0.4.4 時点でのメモ

Ryeをアンインストール

ryeをアンインストール. git bashから実行するとなぜかうまく動作しなかったのでpowershellから実行

# 管理者権限で実行
rye self uninstall

ユーザーディレクトリ下の.rye/config.tomlだけ生き残ってたので手動で削除

uvをインストール

powershellからirm https://astral.sh/uv/install.ps1 | iexを実行すればよいはずだがエラーになったので調べてみると以下のIssueと同じ状況っぽい

https://github.com/astral-sh/uv/issues/2085

SecurityProtocolを指定して再実行するとインストールされた

# ↓1行を$PROFILEに書いといたほうがいい uv self updateしたときも引っかかるので
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12;
irm https://astral.sh/uv/install.ps1 | iex

このIssueにたどり着く前にpipxからインストールを試みたが、その際は某セキュリティソフトに不正なアプリとして検出されてしまった。その際のごちゃごちゃで

  1. pipxでインストール
  2. 上記Issueの手順でインストール
  3. pipxのほうが重複したのでpipx uninstall uv

としたのだが、2の時点ではuvをpowershellから呼び出せたのだが、3でpipx uninstallしたところuvを呼び出せなくなった。
PATH環境変数にuvへのパス（たぶんC:\Users\{User名}\.cargo\bin）は残っていたが、CARGO_HOMEという環境変数が消えていたのでそちらを手動で追加した(同様にC:\Users\{User名}\.cargo\bin)

えんぶんえんぶん

Pythonをinstallする

uv python listして何もインストールされてない状態(<download available>になってる状態)でuv python installしてみる

❯ uv python install 3.12
❯ uv python list
cpython-3.12.6-windows-x86_64-none  AppData\Roaming\uv\python\cpython-3.12.6-windows-x86_64-none\python.exe

❯ uv run python --version
3.12.6
❯ uv run python -c 'print("hello world")'
hello world
❯ uv run --python 3.12 python --version
Python 3.12.6

❯ uv run --python 3.11 python --version
# 3.11をinstallしてない場合はコマンド実行前にinstallされる
Python 3.11.10

installしたインタプリタはグローバルに呼び出せるわけではない

❯ uv python install 3.12
❯ python --version
# pythonは呼び出されない
Python

https://docs.astral.sh/uv/reference/cli/#uv-python-install

A python executable is not made globally available, managed Python versions are only used in uv commands or in active virtual environments.

えんぶんえんぶん

tool機能

npxだったりpipxだったりな機能のやつ

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

  • uvx <package_name>(= uv tool run <package_name>) すると一時領域にパッケージをインストールしてパッケージを使用できる
    • 一時的になのでuv tool listの一覧にはでてこない
  • 恒久的に使いたい場合はuv tool install ruffのようにしてインストールする
    • install するとuv tool listの一覧に表示される
  • インストールされたパッケージは特定のbinディレクトリに保存されるが、binへのPATHが通ってないとインストール時に警告が出る。uv tool update-shellを実行するとPATHを通してくれる。
  • uv tool uninstallでインストールされたパッケージの削除
  • uvx ruff --versionで最新のruff（例えば0.6.7）を使用した後でuv tool install ruff@0.6.0など特定のバージョンをインストールするとuvx ruffも0.6.0を使用するようになる。この状態で特定のバージョンを一時的に実行したければuvx ruff@latest --versionなどすればよいと思う
  • uv tool run(uvx)とuv runの違い
    • uv runは、python example.pyのようにPythonファイルを実行するときに、通常であればvenvをactivateしていなければいけなかったり実行環境を自前で管理しなければいけなかったが、uv run example.pyのように実行すればuvがプロジェクトの依存関係を自動で解決して実行してくれる
    • ruffがインストールされてない状態でuv run ruffなどするとprogram not foundとなる
    • プロジェクトフォルダ(pyproject.tomlがあるフォルダ)でuv runすると実行前に依存関係がインストールされる。プロジェクトに存しないスクリプトを実行する場合uv run --no-projectとするとこの事前インストールが実行されない
  • ❌pipxでもそうだったけどパッケージが古くなった(新しいバージョンが存在する)場合に教えてくれる--outdated的なオプションが欲しい
えんぶんえんぶん

pythonプロジェクト管理

https://docs.astral.sh/uv/guides/projects/
https://docs.astral.sh/uv/concepts/projects/

init

  • uv initとプロジェクト名を指定しない場合、カレントディレクトリ直下にpyproject.tomlを作成
    カレントディレクトリ名がそのままプロジェクト名として作成される
  • uv init hello-worldとプロジェクト名を指定した場合、指定したプロジェクト名のディレクトリを作成して、そのディレクトリ下にpyprojectが作成される

はじめてのスクリプト実行

  • サンプルスクリプト(hello.py)が同時に作成されるの
  • uv python pin 3.10などでバージョン固定
    • initした時requires-python = ">=3.12"とかになってて3.10指定すると失敗する
    • pyproject.tomlを更新してからpinをする
  • uv run hello.pyを実行すると
    • pinしたpythonがインストールされてない場合はインストールされる
    • (ない場合は)uv.lockファイルが生成される
    • (ない場合は).venvフォルダが作成される。pinしたpythonが変更されてたりするといったん削除されて再作成される
    • スクリプトが実行される

依存パッケージ追加・削除・同期

  • uv add boto3とするとpyprojectのdependenciesにパッケージ追加、.venvフォルダにパッケージがインストールされる
    • --no-syncオプション付けるとパッケージのインストールは行わない
    • --devつけるとdev-dependenciesにパッケージ追加
  • uv addとuv pip installの違い
    • add: pyprojectのdependenciesに追加される
    • pip install: 通常のpipと似た動作。pyprojectに追加されず.venvにインストールされる
      venvをactivateしなくてもvenvにパッケージをインストールするイメージ
  • uv add httpx --optional networkでhttpxライブラリをextraパッケージとして追加
    [project.optional-dependencies]
network = [
    "httpx>=0.27.2",
]
  • uv remove httpx --optional networkとするとhttpxは消えるがnetworkオプションは残り続ける
    [project.optional-dependencies]
network = []
  • networkオプションを丸っと消す場合は手動でpyprojectを書き換える必要があるっぽい
  • pyprojectを手動で書き換えた場合はuv syncでuc.lock, .venvを最新の状態に更新する
えんぶんえんぶん

非uvプロジェクトでuv使う

プロジェクト管理でuvは使ってない既存プロジェクトでuv使う場合

  • uv python pin 3.xで.python-version固定(.python-versionがもとからあるならそれ使う)
  • uv venvで.venvフォルダ作成。固定バージョンのインタプリタがなければさきにインストールされる
  • [dev-]requirements.txtでパッケージ管理してる場合
    • uv pip install -r requirements.txt
  • poetryとかpipenvとかの場合
    • uv tool install poetry / uvx poetryなどで既定のツール使うしかないか
  • pyprojectがない(pyproject中にprojectの記述がない)場合にuv runするとerrorになるっぽい
    • error: No 'project' table found in: "......./pyproject.toml"
    • 仕方ないからuvxで実行した
えんぶんえんぶん

v0.5.0でインストール先のフォルダが変更になった

https://github.com/astral-sh/uv/releases/tag/0.5.0
https://github.com/astral-sh/uv/pull/2236

v0.4.xまでは~/.cargo/binにインストールされてたのが~/.local/binに変更になったらしい
windowsの場合はC:\Users\{UserName}\.local/bin

windows環境下でv0.4.20からuv self updateして0.5.0にあげたところ、command not foundとなってしまった。
C:\Users\{UserName}\.cargo/binではなくC:\Users\{UserName}\.cargoの下にuv.exeとuvx.exeがあるが前からそうだっけ？とにかく.local/binにはいなかった