uvでPythonのCLIツールを作成・インストール・実行
Pythonのパッケージ・プロジェクトマネージャーのuvを使うと、CLIツール（コマンドラインツール）を簡単に作成・インストール・実行できる。
自作のツールを適当に作る場合も、環境構築をuvに任せると実行時に仮想環境などを気にしなくていいので便利。
uv自体のインストールは以下の公式ドキュメントを参照。HomebrewやWinGetなどのパッケージマネージャーも利用できる。
本記事におけるuvのバージョンは以下の通り。
$ uv --version
uv 0.7.7 (Homebrew 2025-05-22)
本記事のサンプルのリポジトリは以下。
uvでプロジェクト作成: uv init --package
uv init --packageでプロジェクトを作成する。
最終的にuv toolでインストールして実行するので、--packageオプションを付けてPackaged applicationとする。
$ uv init --package my-uv-tool
Initialized project `my-uv-tool` at `/Users/xxxxx/Documents/my-uv-tool`
以下のようなファイル・ディレクトリが生成される。
$ tree my-uv-tool
my-uv-tool
├── pyproject.toml
├── README.md
└── src
└── my_uv_tool
└── __init__.py
作成したディレクトリに移動してuv runでプロジェクト名（my-uv-tool）を指定すると、デフォルトのコマンドが実行できる。
$ cd my-uv-tool
$ uv run my-uv-tool
Hello from my-uv-tool!
以降の例では、このままプロジェクトのルートディレクトリ（pyproject.tomlやREADME.mdがあるディレクトリ）をカレントディレクトリとして実行しているものとする。
依存ライブラリを追加: uv add
ツール内でサードパーティライブラリを使いたい場合はuv addで追加する。
$ uv add numpy
clickやfireといったCLIフレームワークを使用するときも同様にuv addで追加すればよい。
依存ライブラリを削除するのはuv remove。
コードを修正・追加
デフォルトでは、src/my-uv-tool/__init__.pyにmain()関数が定義されている。
__init__.py:
def main() -> None:
print("Hello from my-uv-tool!")
このmain()関数は不要であれば削除していいが、__init__.pyファイル自体は中身が空でも残しておく。
ここでは例としてcli.pyとutils.pyをsrc/my_uv_toolディレクトリに追加する。
cli.py:
from my_uv_tool import utils
def main():
print('Hello from cli.py!')
print(f'NumPy version: {utils.numpy_version()}')
utils.py:
import numpy as np
def numpy_version():
return np.__version__
pyproject.tomlでエントリーポイントを設定
追加したファイルの関数をコマンドとして実行するために、pyproject.tomlの[project.scripts]にエントリーポイントを設定する。
デフォルトでは、プロジェクト名（my-uv-tool）に"my_uv_tool:main"（__init__.pyのmain()に対応）が割り当てられている。
[project.scripts]
my-uv-tool = "my_uv_tool:main"
例として、以下のようにエントリーポイントを修正・追加する。
[project.scripts]
my-uv-tool = "my_uv_tool.cli:main"
my-np-version = "my_uv_tool.utils:numpy_version"
左辺には任意のコマンド名、右辺には実行する関数を指定する。例えば、my_uv_tool/cli.pyのmain()関数は"my_uv_tool.cli:main"のように指定する。
uv runでコマンド名を指定すると実行できる。
$ uv run my-uv-tool
Hello from cli.py!
NumPy version: 2.2.6
$ uv run my-np-version
2.2.6
作成したツールをインストール: uv tool install
作成したツールをインストールするには、uv tool installでプロジェクトディレクトリのパスを指定する。
例ではプロジェクトのルートディレクトリにいるので.を指定すればよい。
$ uv tool install -e .
Installed 2 executables: my-np-version, my-uv-tool
ここで、-e（--editable）オプションを付けると、Editable（編集可能）モードでインストールされ、コードの更新が即座に反映される。開発中は便利。ただし、pyproject.tomlの更新（エントリーポイントの変更・追加など）は自動で反映されないので、ツールのアンインストール・再インストールが必要。
uv toolのbinディレクトリが環境変数PATHに追加されていないとインストール時に警告が出るので要設定。詳細は次節を参照。
PATHが正しく設定されていれば、インストール後は設定したコマンドをどこからでも実行できる。仮想環境に入ったりする必要はない。
$ my-uv-tool
Hello from cli.py!
NumPy version: 2.2.6
$ my-np-version
2.2.6
インストールされているツールの一覧はuv tool list。
$ uv tool list
my-uv-tool v0.1.0
- my-np-version
- my-uv-tool
アンインストールはuv tool uninstall。プロジェクト名を指定する。
$ uv tool uninstall my-uv-tool
Uninstalled 2 executables: my-np-version, my-uv-tool
uv tool installによるツールのインストール場所はuv tool dirで確認できる。このディレクトリを手動で操作することは推奨されておらず、あくまでも確認用。
$ uv tool dir
/Users/xxxxx/.local/share/uv/tools
uv toolのbinディレクトリを環境変数PATHに追加
uv toolでインストールしたツールをどこからでも実行するには、binディレクトリが環境変数PATHに含まれている必要がある。
binディレクトリがPATHに含まれていないとuv tool install実行時に警告が出る。
以下はWindowsでの例。
warning: `C:\Users\xxxxx\.local\bin` is not on your PATH. To use installed tools,
run `$env:PATH = "C:\Users\xxxxx\.local\bin;$env:PATH"` or `uv tool update-shell`.
警告に書いてあるように、uv tool update-shellでPATHを設定できる。
$ uv tool update-shell
実行後はターミナルなどを再起動しないと反映されない。Windowsではユーザーのサインアウト・再サインインが必要だった。
binディレクトリの場所などの詳細は公式ドキュメントを参照。
作成したツールを公開
作成したツール（パッケージ）をPyPIで公開する手順は以下の公式ドキュメントを参照。
PyPIに登録するほどではない場合も、Gitレポジトリを公開すればそこからインストールできる。
$ uv tool install git+https://github.com/nkmk/my-uv-tool
タグやブランチなどの指定方法は以下の公式ドキュメントを参照。uv addの説明だが、uv tool installでも同じ。