uvを使ってPython実行環境を整理してみた

#Python

nokomoro3

2024.08.31

こんちには。

データ事業本部インテグレーション部機械学習チームの中村( @nokomoro3 )です。

今日は以下の記事で紹介されてuvを知ったので、使ってみたいと思います。

（ちなみに少し触った感じでも、めちゃめちゃ速く、2文字のタイピングで済む時点で既にかなりお気に入りです。）

公式ドキュメントは以下となります。

動作環境

私のPCの動作環境は以下とします。

OS: Windows 10
ターミナル: Bash for Windows (Git for Windowsに付属のもの)
- ときどきPowershellも使います
uv: 0.4.0 (d9bd3bc7a 2024-08-28)

インストール

以下に沿ってインストールします。

まずは以下を実行します。

# Powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

すると、uvが C:\Users\{ユーザ名}\.cargo\bin にデフォルトでインストールされますので、環境変数PATHにこちらのフォルダが設定されていない場合は設定をします。

# Powershell
$oldValue = [System.Environment]::GetEnvironmentVariable("PATH", "User")
$newValue = $oldValue + ";C:\Users\{ユーザ名}\.cargo\bin"
[System.Environment]::SetEnvironmentVariable("PATH", $newValue, "User")

ターミナル等を再起動すれば、uvとuvxが使用できるようになっています。

uv --version
# uv 0.4.0 (d9bd3bc7a 2024-08-28)

uvx --version
# uv-tool-uvx 0.4.0 (d9bd3bc7a 2024-08-28)

補足：既存環境の削除

uvのインストールに伴って、不要となったものを一通り消しておきます。こちらは既存の環境が動かなくなる可能性がありますので自己責任＋ご自身の環境にあった対応をお願いいたします。

私の場合は以下の記事でセットアップしていましたので、pyenv、poetry、pipx、scoopを消しておきました。

まずはアンインストールを行います。

# poetryの削除
pipx uninstall poetry

# pipxの削除
scoop uninstall pipx

# Pythonの削除
scoop uninstall python

データも削除しておきます。

C:\Users\{ユーザ名}\.pyenv
C:\Users\{ユーザ名}\pipx
C:\Users\{ユーザ名}\scoop
C:\Users\{ユーザ名}\AppData\Local\pypoetry\Cache\virtualenvs
C:\Users\{ユーザ名}\AppData\Local\pip
C:\Users\{ユーザ名}\AppData\Local\pipenv
C:\Users\{ユーザ名}\AppData\Local\pip-tools
C:\Users\{ユーザ名}\AppData\Local\pypa
C:\Users\{ユーザ名}\AppData\Local\pypoetry

環境変数も不要そうなものは消しておきました

PATHから以下を削除
- C:\Users\{ユーザ名}\.pyenv\pyenv-win\bin
- C:\Users\{ユーザ名}\.pyenv\pyenv-win\shims
- C:\Users\{ユーザ名}\scoop\apps\python\current\Scripts
- C:\Users\{ユーザ名}\scoop\apps\python\current
- C:\Users\{ユーザ名}\scoop\shims
PYENVの削除
PYENV_HOMEの削除
PYENV_ROOTの削除

プロジェクトの新規作成

新規にディレクトリと環境を作成するには、以下を実行します。

uv init {プロジェクト名}

すると以下のようなファイルが作成されます。

hello.py
pyproject.toml
README.md

0.4.0 から uv init で --app と --lib というオプションが使えるようになっており、パッケージとしてプロジェクトをビルドする必要がない場合は --app を使います。
--lib を使用すると、 src というフォルダも作成され、パッケージとして使用できるようになります。元々は --lib の動作だけでしたが、0.4.0 のアップデートに伴い --app が追加され、デフォルトになっているようです。

作成される hello.py は削除しても構いませんが、 README.md も消してシンプルにしたい場合は、以下の行を削除すればOKです。

pyproject.toml

readme = "README.md"

また、 --no-readme というオプションもありますので、そちらを設定して uv init しても良いと思います。

結論としては私の場合は以下を使っていくことにしました。

uv init {プロジェクト名} --no-readme --app

以降はプロジェクト内で作業をします。

cd {プロジェクト名}

Pythonバージョンの設定

デフォルトでは最新のPythonが使用されますが、別のバージョンを使用したい場合は以下のようにします。

uv python pin 3.11.8
# warning: No interpreter found for Python 3.11.8 in managed installations, system path, or `py` launcher
# Pinned `.python-version` to `3.11.8`

pinしたPythonバージョンが以下の requires-python より古い場合は、書き換える必要があります。

pyproject.toml

requires-python = ">=3.12"

その後、uv sync を実行することで実際にダウンロード等が走ります。

uv sync
# Using Python 3.11.8
# Creating virtualenv at: .venv
# Resolved 1 package in 5ms
# Audited in 0.02ms

インストールされたPythonは以下のパスに置かれるようです。

C:\Users\{ユーザ名}\AppData\Roaming\uv\python

またsyncを実行することにより、仮想環境も .venv に構築されます。

補足：使用可能なPython一覧を確認する

既にダウンロードされて使用可能なPythonを調べるには以下を実行すればOKです。

uv python list # 既にインストール済みのもの

ダウンロードされてないものを含めて一覧を取得する場合は以下となります。

uv python list --all-versions # 全バージョン
uv python list --all-platforms # 全プラットフォーム

補足：手動でインストール・アンインストールする

通常、存在しなければ uv sync 時に自動でインストールされますが、手動でインストール・アンインストールしたい場合は以下を実行します。

uv python install
uv python uninstall

仮想環境上のPythonを実行する

2つ方法があり、 uv run を使う方法とactivateをする方法があります。

uv runを使う

まずは uv run を使う方法ですが、以下を実行すればOKです。

uv run python

Python 3.11.8 (main, Feb 25 2024, 03:41:44) [MSC v.1929 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>>

以下でどこのPythonを使っているか確認することができます。

uv run python -c "import sys; print(sys.prefix)"
# {プロジェクトの絶対パス}\.venv

ファイルを実行する場合は以下でOKです。

uv run hello.py

activateする場合

pythonを uv run python と書き換えて回るのが面倒な場合はこちらが良いかもしれません。

以下を実行すると、

source .venv/Script/activate
# source .venv/Script/activate.ps1 # Powershellの場合はこちら

pythonが仮想環境のものを指すようになります。

python -c "import sys; print(sys.prefix)"
# {プロジェクトの絶対パス}\.venv

パッケージの管理

追加・削除はそれぞれaddとremoveで実行できます。

uv add {パッケージ名}
uv remove {パッケージ名}

gitレポジトリの指定やローカルディレクトリなども可能です。指定可能な形式は以下もご参照ください。

また、開発用のパッケージとしてのみ必要な場合は --dev オプションを付ければOKです。

uv add pytest --dev

補足：パッケージツリーの表示

依存関係がわかるパッケージツリーを以下のコマンドで表示することができます。

uv tree

# Resolved 8 packages in 1ms
# sample-uv-2 v0.1.0
# └── boto3 v1.35.10
#     ├── botocore v1.35.10
#     │   ├── jmespath v1.0.1
#     │   ├── python-dateutil v2.9.0.post0
#     │   │   └── six v1.16.0
#     │   └── urllib3 v2.2.2
#     ├── jmespath v1.0.1
#     └── s3transfer v0.10.2
#         └── botocore v1.35.10 (*)
# (*) Package tree already displayed

配布されたファイルを元に仮想環境を作成する場合

pyproject.toml や uv.lock などがある状態のフォルダで、仮想環境をPC内に作るには以下を実行します。

uv sync

requirements.txtを使う

既に requirements.txt があり、それを読み込む場合は以下を使います。

uv add -r requirements.txt

逆に requirements.txt として配布する必要がある場合は、以下を使います。

uv pip freeze > requirements.txt

requirements.txtの中身の例は以下です。

requirements.txt

boto3==1.35.9
botocore==1.35.9
jmespath==1.0.1
python-dateutil==2.9.0.post0
s3transfer==0.10.2
six==1.16.0
urllib3==2.2.2

補足：Lambda Layerとして使う

uv pip の応用として、Lambda Layerとして使いたい場合は以下を実行すれば良さそうです。（そもそも.venvそのものをどうにかすればできそうな気もしますが）

uv pip freeze > requirements.txt
uv pip install -r requirements.txt --target ./dist/python

上記をzipにするコマンドはお好みでOKです。Powershellからだと以下のようにしてできます。

Compress-Archive -Path .\dist\python -DestinationPath archive.zip

# zipコマンドの場合
# zip -r archive.zip ./dist/python

グローバルなツールをインストールする

ruffやsqlfluffなどをグローバルに使いたい場合は以下を実行します。

uvx sqlfluff --version
# ruff 0.6.3

uvxは uv tool run のエイリアスで、インストールせずに使う npx のようなイメージかと思います。
インストールして使いたい場合は、以下のようにすればOKです。

uv tool install ruff
ruff --version
# ruff 0.6.3

uv tool install でインストールしたものは以下の場所に配置されます。

C:\Users\{ユーザ名}\.local\bin

上記が環境変数PATHに無い場合は追加されてください。

$oldValue = [System.Environment]::GetEnvironmentVariable("PATH", "User")
$newValue = $oldValue + ";C:\Users\{ユーザ名}\.local\bin"
[System.Environment]::SetEnvironmentVariable("PATH", $newValue, "User")