uvで始めるPythonプロジェクト管理

想定読者

• モダンなPythonのプロジェクト管理に興味がある人
• 中級者未満

はじめに

先日Pythonのプロジェクト管理ツールであるRyeの導入記事を書きました。

似たようなPythonプロジェクト管理ツールで、さらに高速と言われているuvというものがあるらしいので、今回はこちらを試してみようと思います。

下記が公式サイトなので、詳細は公式サイトを見てください。上級者の方は、公式サイトを読んで頂いた方が良いと思います。

環境

MacBookPro
Apple M3 Max
macOS Sequoia15.0.1

uvのインストール

uvのインストールは公式サイトに載っていますが、インストール方法がいくつかあります。

公式で推奨されている方法です。基本的には下記コマンドを使っておけば大丈夫です。

curl -LsSf https://astral.sh/uv/install.sh | sh

下記コマンドの場合、開発環境ごとに異なるバージョンのuvを使用したい場合に主に使用することになります。

pip install uv

Mac向けの選択肢で、私が調べた限りあまり差はありませんでした。
特にこのコマンドであるメリットもないかなと。

brew install uv

インストールが完了したら、パスを通しましょう。
pipでインストールした場合は、パスを通す必要はないと思います。

source $HOME/.cargo/env

インストールされたか確認するついでに最新版にアップデートしてしまいます。

uv self update

ここまでエラーが出なければ、uvを使うことができる状態です。

uvでプロジェクト管理をする

既存のプロジェクトでuvを使用する場合は、プロジェクトのルートディレクトリで下記コマンドを実行します。

uv init

なんやかんや動いて。
hello.py
pyproject.toml
.python-version
が勝手に作成された。

続きまして、現在使用可能なPythonのバージョンを調べます。

$ uv python find
/Library/Frameworks/Python.framework/Versions/3.12/bin/python3

現在は3.12のバージョンになっているようです。これは私の環境のPythonと同じになっていると思います。
せっかくなので、最新版を使いたい。ということで、uvで使用可能なPythonのバージョンを調べます。

$ uv python list
cpython-3.13.0-macos-aarch64-none     <download available>
cpython-3.12.7-macos-aarch64-none     <download available>
cpython-3.12.6-macos-aarch64-none     /opt/homebrew/opt/python@3.12/bin/python3.12 -> ../Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.12.0-macos-aarch64-none     /usr/local/bin/python3.12 -> ../../../Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.12.0-macos-aarch64-none     /usr/local/bin/python3 -> ../../../Library/Frameworks/Python.framework/Versions/3.12/bin/python3
cpython-3.12.0-macos-aarch64-none     /Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.12.0-macos-aarch64-none     /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 -> python3.12
cpython-3.11.10-macos-aarch64-none    <download available>
cpython-3.10.15-macos-aarch64-none    /opt/homebrew/opt/python@3.10/bin/python3.10 -> ../Frameworks/Python.framework/Versions/3.10/bin/python3.10
cpython-3.10.15-macos-aarch64-none    <download available>
cpython-3.10.5-macos-aarch64-none     /usr/local/bin/python3.10 -> ../../../Library/Frameworks/Python.framework/Versions/3.10/bin/python3.10
cpython-3.10.5-macos-aarch64-none     /Library/Frameworks/Python.framework/Versions/3.10/bin/python3.10
cpython-3.10.5-macos-aarch64-none     /Library/Frameworks/Python.framework/Versions/3.10/bin/python3 -> python3.10
cpython-3.9.20-macos-aarch64-none     /opt/homebrew/opt/python@3.9/bin/python3.9 -> ../Frameworks/Python.framework/Versions/3.9/bin/python3.9
cpython-3.9.20-macos-aarch64-none     <download available>
cpython-3.9.6-macos-aarch64-none      /Applications/Xcode.app/Contents/Developer/usr/bin/python3 -> ../../Library/Frameworks/Python3.framework/Versions/3.9/bin/python3
cpython-3.9.5-macos-x86_64-none       /usr/local/bin/python3.9 -> ../../../Library/Frameworks/Python.framework/Versions/3.9/bin/python3.9
cpython-3.9.5-macos-x86_64-none       /usr/local/bin/python -> /usr/local/bin/python3.9
cpython-3.9.5-macos-x86_64-none       /Library/Frameworks/Python.framework/Versions/3.9/bin/python3.9
cpython-3.9.5-macos-x86_64-none       /Library/Frameworks/Python.framework/Versions/3.9/bin/python3 -> python3.9
cpython-3.8.20-macos-aarch64-none     <download available>
pypy-3.10.14-macos-aarch64-none       <download available>
pypy-3.9.19-macos-aarch64-none        <download available>
pypy-3.8.16-macos-aarch64-none        <download available>

現在最新の3.13.0が使用できるのでインストールします。

$ uv python install 3.13
Searching for Python versions matching: Python 3.13
Installed Python 3.13.0 in 3.01s
 + cpython-3.13.0-macos-aarch64-none

インストールが完了したらRyeと同じくpinでPythonのバージョンを指定します。

$ uv python pin 3.13
Updated `.python-version` from `3.12` -> `3.13`

ライブラリの追加

ライブラリの追加はuv addでできます。

$ uv add pytest
Using CPython 3.13.0
Creating virtual environment at: .venv
Resolved 6 packages in 287ms
Prepared 4 packages in 113ms
Installed 4 packages in 6ms
 + iniconfig==2.0.0
 + packaging==24.1
 + pluggy==1.5.0
 + pytest==8.3.3

ライブラリを追加した後はuv syncで仮想環境に変更を同期させます。

uv sync

他の大まかなコマンドは下記のようになっています。
この辺は公式ドキュメントに詳しく書かれています。
何か変更をしたらuv syncを忘れないようにしましょう

uv init 新しい Python プロジェクトを作成します。
uv add プロジェクトに依存関係を追加します。
uv remove プロジェクトから依存関係を削除します。
uv sync プロジェクトの依存関係を環境と同期します。
uv lock プロジェクトの依存関係のロックファイルを作成します。
uv run プロジェクト環境でコマンドを実行します。
uv tree プロジェクトの依存関係ツリーを表示します。

実行

uvの環境で実行したい場合はuv runで実行できます。
例

uv run pytest

まとめ

uvを実際に使ってみると、早くて快適です。
機能的にも現状不満はないです。
Pythonのバージョンと仮想環境を一緒に管理できるので初心者向きだと思います。
公式ドキュメントも日本語はありませんが充実しているので、ブラウザの翻訳機能を使えば十分に読めます。
Ryeに続き、uvにも触れてしまったので、この辺の違いとかを整理したいと思っています。
ではでは

Ryeの使い方は下記から、どうぞ。