はじめに
海外のPython関連のGitHubリポジトリを見るとuvという管理ツールを使う前提になっていることが増えてきました。uvをざっと使ってみました。使い方とそのメリットを個人的にメモしておきます。内容の正確性には自信が無いので、正しい情報は公式ページをご確認ください。
uv を使用するメリット
- 複数のPython環境を管理できる。pyenvはすぐ使い方忘れるので便利かも。でも自分は採用しないことにした（理由は後述）
- どのパッケージをインストールしているのかがtomlファイル内に自動的に記載されるのでわかりやすい
- インストール・アンインストールが高速。キビキビした動作は気持ちが良い
-
uv tool runを使うとローカル全体で使用できる分離した仮想環境にツールが自動的にインストールされて実行できる。環境を汚さない
仮想環境についてはVSCodeを使用しているならPython Environmentを併用するととても楽チンなのでお勧めです。あまり知られていない拡張機能みたいですけど。仮想環境の簡単な管理ツールが欲しいならこの拡張機能だけでも十分便利ですのでお試しください。
プロジェクトの作成
- カレントフォルダをPythonプロジェクトにする
uv init - カレントフォルダの下に名前をつけたPythonプロジェクトを作成する
uv init <ProjectName>
初期状態ではファイルが5種類作成されます。
- pyproject.toml
- 仮想環境のPythonバージョンを指定するための.python-version
- .gitignoreファイル
- サンプルのmain.py
- README.md
プロジェクト全体はgit管理下に置かれます。
次のようなオプションがあります。
README.mdは不要
uv init --no-readme
.python-versionファイルは不要
uv init --no-pin-python
git管理下に置かない
uv init --vcs none
仮想環境の作成
最初、仮想環境は存在してません。プロジェクト内部で何かしらのuvコマンドを発行すると自動的に.vnevフォルダが作成され、仮想環境となります。例えばこんなコマンドを発行します。
uv run main.py
uv sync
とりあえずプロジェクトを作成したら、uv syncを発行しておくのが良さそうです。
パッケージ管理
公式ページではManaging dependeciesに記載があります。
パッケージ情報はpyproject.tomlファイルに記載されていくので、何がインストールされているのかが一目瞭然です。Node.jsのpackage.jsonによるパッケージ管理によく似ています。
- パッケージの追加
uv add <package> - パッケージの削除
uv remove <package>
tomlファイルを直接修正してパッケージを追加・削除・更新した場合は、uv syncを叩くと反映されます。これは便利。（本当にNode.jsのpackage.jsonによく似てます）
uv 越しに pip コマンドもどきが使用できます。requirements.txtを使用することもできます。
uv pip install <package>
uv pip install -r requirements.txt
ただし、この方法でインストールしたパッケージはpyproject.tomlファイルに反映されません。そしてこのuv越しのpipは公式のpipコマンドではなく、uvによる実装だそうなので、全く同じ動作をするわけでは無いことに注意が必要です。
Python製ツール
ツールの使用はプロジェクトだけで使用する場合、仮想環境下にインストールされ、プロジェクト横断的にインストールする場合はプロジェクトの外にインストールされるようです。
プロジェクト内部だけでツールを使用する
1. ツールのインストール
プロジェクト直下で次のコマンドでツールをインストールします。パッケージのインストールと同じです。
uv add <tool>
例えば型チェックをするmypyを入れるなら
uv add mypy
となります。
2. ツールの実行
uv run <tool>
uv run コマンドはuv run main.pyのようにファイルを指定してスクリプト実行するだけでなく、ツールの実行も可能です。
プロジェクト横断でツールを使用する
こちらは少しややこしいです。uv toolコマンドを使うのですが、ツール管理を行う形でインストールするか、管理しないでインストールするかでインストール先と実行コマンドが異なります。
ツール管理をするでインストールする場合
ここではツールとしてmypyを使用する場合を例にします。
ツールのインストール
uv tool install mypy
初回インストール時は.local/binフォルダがPATHに通っていないため、自分でShellに追加するか、次のコマンドを叩くのかどちらかを選択するように促されます。
uv tool update-shell
update-shellを叩くと、.local/binフォルダにパスを通すためのファイル（MacOSの場合は.zshenvファイル）が作成されますのでこちらを選択するのが良いでしょう。Shellを立ち上げ直すと、自動的に読み込まれてtoolが使えるようになります。
ツールの実行
プロジェクト直下で次のコマンドを叩きます。
mypy .
PATHが通った環境にインストールされているので、ツールそのものを実行できます。 間違ってもuv tool run mypy .としてはいけません。uv tool runコマンドは別の意味を持つからです。（後述）
インストール済みツールの一覧表示
uv tool list
ツールのアンインストール
uv tool uninstall <tool>
ツールのインストール先PATHを表示
uv tool dir
ツール管理をしない形式でインストールする場合
uv toolコマンドを使うと、ツール管理をする形式になりますが、ダウンロードしたツールをキャッシュとしてあくまでも一時的に扱う方法があります。
uvx mypy .
インストールコマンドは不要です。いきなりツール名とツールが必要な引数を渡せば、キャッシュにない場合は自動的にダウンロードしてさらにツールを実行します。
そしてややこしいことにこのuvxコマンドはuv tool runコマンドの短縮系なのです。なので、すごく注意必要です。
一時的にダウンロードしたツールは、uvのcacheディレクトリに存在するようです （公式情報ではありません） 。アンインストールする場合はcacheに対して操作することになります。
キャッシュの中の特定のパッケージを削除
uv cache clean mypy
このコマンドでmypyは消えてくれますが、mypyが依存しているパッケージまでは消してくれません。
全てのキャッシュを削除
uv cache clean
キャッシュの場所を表示
uv cache dir
まとめると
-
uv tool installでインストールしたツールは、Globalにツールとして実行可能 -
uvxまたはuv tool runで一時的にインストールしたツールは常にuvxまたはuv tool runで実行しなければならない
となります。
uvxでの実行は手軽で良いのですが、cacheにダウンロードされたツールの一覧を表示する機能ないことには注意が必要です。
MCP Serverとしてのツールを使用する場合、uvxコマンドでMCP Serverのダウンロードと実行をする場合が多いようですが、どのMCP Serverがインストールされているのかを把握できなってしまう問題があるということです。
Python 複数バージョンの管理
uv では Python 自身の管理もできます。複数のバージョンをインストールしておいて、各プロジェクトの仮想環境使用時に選択できます。
が、個人的にはuvでのバージョン管理はやりません。それは公式ページの次の注意書きを見たからです。
uv によってインストールしたPythonはグローバルで使用できない、例えばpythonコマンドが使えません。
pythonコマンドにパスが通らないとなると、色々と問題が出そうです。例えばIDEのインテリセンスなどに影響が出そうです。出ないかもしれませんが。
なので、私はuvではPythonのバージョン管理はしません。
コマンドは以下の通りです。
インストール済みPythonの一覧。uvでインストールした以外のPythonも検知してくれるのは便利。
uv python list
最新版のPythonのインストール
uv python install
特定バージョンのPythonのインストール
uv python install 3.12
最後に
実はMCP Serverとしてuvxを使用されていることがとても多く、仕方なくuvを調べ始めました。uvxの挙動がよく分からず、コマンドを色々と叩いて挙動を確認しましたので、ダウンロード先がcacheであることはあくまで私の個人的な見解であることにご注意ください。