[Python] uvでよく使うコマンドをケースごとに整理した

Python 3.11あたりから仮想環境を作ってパッケージをインストールすることが普段の使い方になってきました。最初はpyenvで複数バージョンのPythonを管理して、PoetryでPythonパッケージのプロジェクト管理を行っていましたが、今はAstralのuvが使っていて楽に感じるようになってきました。Rustで書かれていて動作が非常に早いというのもありますが、ディレクトリ(フォルダー)を移動するたびにsource .venv/bin/activateとdeactivateをタイプしなくてよいのが楽に感じる理由だと思います。

uvは、Pythonの仮想環境管理、依存関係解決、実行環境セットアップを一体化したツールです。uvには数多くのコマンドがありますが、日常的によく使うシナリオに分けて代表的なコマンドを整理すれば、そんなに多くならないのではないかと思います。以下のようにまとめてみました。

• Pythonの実行環境を整えるときによく使うコマンド(ランタイム用)
• Pythonパッケージのプロジェクトを管理するときによく使うコマンド(開発用)

Pythonの実行環境を整えるときによく使うコマンド(ランタイム用)

本番・実行環境でPythonの実行基盤を整えるときに使うコマンドです。ちょっとしたスクリプトの実行にも適しています。

コマンド	説明
uv python install Pythonバージョン	指定したPythonバージョンをインストールします。
uv python pin Pythonバージョン	.python-versionファイルを作成し、バージョンを固定します。 Pythonバージョン を省略すると、.python-versionファイルのバージョンを表示します。
uv venv	仮想環境を作成します。 .venvディレクトリが生成されます。
uv pip install パッケージ名 …	必要なパッケージをインストールします。
uv run スクリプト名.py uv run python	仮想環境内でスクリプトを実行します。( uv run python スクリプト名.py と同じ) pythonだけを指定すると対話モードでPythonを実行します。
uvx コマンド名 uvx コマンド名@latest uvx コマンド名@バージョン	コマンドラインツール(CLIツール)を一時的に実行します。pip install不要です。 最新版を動かしたいときは、コマンド名の後ろに@latestを付けます。@バージョンでも指定できます。
uv tool install パッケージ名 uv tool install パッケージ名@latest uv tool install パッケージ名@バージョン	CLIツールをインストールします。 最新版をインストールしたいときは、パッケージ名の後ろに@latestを付けます。@バージョンでも指定できます。

例えばJupyterLabを使う場合は、以下のような感じになります。

# Pythonのセットアップ
uv python install 3.14

# 作業ディレクトリを作成
mkdir -p work
cd work

# Pythonバージョンを固定
uv python pin 3.14

# 仮想環境を構築
uv venv

# JupyterLabをインストール
uv pip install jupyterlab

# numpyとmatplotlibをインストール
uv pip install numpy matplotlib

# JupyterLabを実行
uv run jupyter lab

uvxは、pipxみたいな感じでコマンドラインツールを実行するのに便利です。uv tool runの別名で、同じ振る舞いをします。

インストールするときはuv tool installを使います。PyPIに公開しなくともGitHubのリポジトリから直接ツールを使うことができるのは便利です。

# pycowsayを使う
uvx pycowsay 'hello world!'

# GitHubのリポジトリからCLIツールを使う
uvx --from git+https://github.com/yamakox/vue3-fastapi vue3-fastapi

# これは公式には説明されていない使い方だが動く (v0.9.7時点)
uvx git+https://github.com/yamakox/vue3-fastapi

# GitHubのリポジトリからCLIツールをインストールする
uv tool install git+https://github.com/yamakox/vue3-fastapi

vue3-fastapi

蛇足ですが、 uvx GitHubリポジトリ という書き方は公式のドキュメントに書かれていません。調べてみると、uvのIssuesの中に「feature: uvx for github repos #8199」というIssueが見つかる程度でした。 —from GitHubリポジトリ コマンド名 は煩わしいので、公式のドキュメントでもサポートしてほしい機能です。

Pythonパッケージのプロジェクトを管理するときによく使うコマンド(開発用)

Pythonパッケージのプロジェクトを構築・管理・開発するときに使うコマンドです。特にuvはPoetryなどのバックエンドとも連携できます。Poetryを使っている理由は後述します。

コマンド	説明
uv python install Pythonバージョン	開発で使用するPythonバージョンをインストールします。
uv init —python Pythonバージョン \ —build-backend poetry プロジェクト名	Poetryを使った新規プロジェクトを初期化します。
uv add パッケージ名 …	依存パッケージを追加します。pyproject.tomlが更新されます。
uv add —dev 開発用パッケージ名 …	開発時のみ使う依存関係を追加します。
uv sync	pyproject.tomlをもとに依存関係を同期（インストール）します。特にgit clone直後に使用します。
uv build	プロジェクトをパッケージ化します。

新しいPythonプロジェクトを作成するときは、以下のような感じになります。

# Pythonのインストール
uv python install 3.14

# 開発用ディレクトリへ移動
cd ~/develop

# 新規プロジェクト作成（Poetryバックエンド）
uv init --python 3.14 --build-backend poetry myproject

# プロジェクトへ移動
cd myproject

# 依存パッケージを追加
uv add fastapi uvicorn

# 開発用パッケージを追加
uv add --dev pytest black

# 依存関係を同期（特にclone直後に使用）
uv sync

# テスト実行
uv run pytest

# プロジェクトをパッケージ化
uv build

2025年10月14日時点での最新版0.9.2では、デフォルトのビルドバックエンドはuv_buildですが、私は以下の理由でPoetryをビルドバックエンドに使っています。

• poetry-dynamic-versioningのおかげで、Gitのコミットにバージョンタグを付けるだけでパッケージのバージョンを更新できるのは非常に便利です。※追記: 以下のブログを書きました。
• HTMLや画像などの静的ファイルをパッケージ内に含めるためのincludeが正しく動作します。(0.9より前のバージョンで使われていたhatchlingはincludeの設定がうまくできませんでした。uv_buildでは未確認です。)
• pyproject.tomlの書き方が分かりやすいのもPoetryを使っている理由です。全体的にドキュメントが充実していて親切だと思います。

[Python] uvとpoetry-dynamic-versioningでバージョン管理(2025年10月版) y-app.tech

uv標準のビルドバックエンドはまだGitなどのバージョン管理システムに登録してあるバージョン番号をビルドしたパッケージに反映できていないため、Poetryをビルドバックエンドに使います。

uvが想定している主な用途分野(モード)

uvが備える機能は非常に豊富なので、AIにまとめてもらいました。以下のような用途分野(モード)をカバーすることを目指しているとのことです。

モード	主な目的	説明
Python 実行環境管理 / Python バージョン管理	複数バージョンの Python をインストール／切り替え	uv python コマンド群で、Python のバージョン管理を扱う。
プロジェクト管理 / 依存関係管理	Python プロジェクトのセットアップ、依存関係、ロック、スクリプト実行	uv init, uv add / remove / sync / lock, uv run, uv build, uv publish など
ツール実行 / 管理（CLI ツール）	ruff や black などの開発ツールをインストール／実行	uv tool run / uvx, uv tool install / upgrade / list など
スクリプト実行（スクリプトとその依存性管理）	単一ファイルスクリプトに対して、依存を定義して実行環境を自動構成	uv run script.py や uv add --script, uv lock --script など
ローカル仮想環境の操作	uv venv などで仮想環境を手動操作する	伝統的な virtualenv / venv 相当の操作を提供
パッケージビルド / 公開	プロジェクトをパッケージ化して、PyPI などに公開	uv build, uv publish など
その他・運用補助	キャッシュ管理、uv 自体のセルフ更新、認証管理など	uv cache, uv self, uv auth など

例えば、pyproject.tomlの依存関係を手作業で追加・削除したときはuv lockが必要になりますし、uvをバージョンアップするときはuv self updateを使います。運用中や開発中には色々なことが起こり得ると思いますので、そのときはuvコマンド群の中に解決する方法が無いか都度調べていけばよいかなと考えています。