uvを使ったPython開発では、どのコマンドを使うかを最初に決めておくと迷いません。
uvには多くのサブコマンドがありますが、実務で日常的に使うものは限られています。
この記事では、pipやvenvを使わない前提で、uv運用において実際に使うコマンドを整理します。
コマンドを一覧で確認でき、その後に用途別の説明を見る構成にしています。
この記事で分かること
この記事で説明する内容
この記事では、uvの概要は詳しく説明しません。
uvとは何か、なぜ使うのかといった内容については、以下の記事で整理しています。
ここでは、実務で実際に使うコマンドについて説明します。
uvを導入済みで、日常の開発作業で迷わずコマンドを使いたい方向けの記事です。
uv 基本コマンド一覧
まず、実務で使用するuvコマンドを一覧でまとめます。
基本的には、この表にあるコマンドだけを使えば運用できます。
uvコマンドはWindows、Linuxのどちらでも同じように使用できます。
| コマンド | 用途 |
|---|---|
| uv init | プロジェクト作成 |
| uv python pin | Pythonバージョン固定 |
| uv add | パッケージ追加 |
| uv add –dev | 開発用パッケージ追加 |
| uv remove | パッケージ削除 |
| uv sync | 依存関係の同期 |
| uv lock | lockファイル生成 |
| uv run python | Python実行 |
これ以降、この一覧に沿って、「何のために使うか」「実行すると何が起きるか」を説明します。
プロジェクト作成・設定
uvを使った開発は、最初にプロジェクトを作成するところから始めます。
ここでは、uv initを使います。
uv initこのコマンドを実行すると、次のようにプロジェクトのルートにpyproject.tomlが生成されます。
uvでは、このpyproject.tomlを中心に、依存関係や設定を管理します。
venvを作成したり、有効化したりする操作は不要です。
ディレクトリ: C:\Users\xxx\projects\sample
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 2026/02/01 22:17 109 .gitignore
-a---- 2026/02/01 22:17 5 .python-version
-a---- 2026/02/01 22:17 84 main.py
-a---- 2026/02/01 22:17 152 pyproject.toml
-a---- 2026/02/01 22:17 0 README.md
Pythonのバージョンを固定したい場合は、次にuv python pinを使います。
uv python pin 3.12このコマンドを実行すると、プロジェクトで使用するPythonバージョンが固定されます。
チーム作業や、後から環境を再現する場合に有効です。
パッケージ管理
パッケージの追加は、uv addを使います。
pip installの代わりとして使用します。
uv add requestsこのコマンドを実行すると、requestsが依存関係として追加され、次のようにpyproject.tomlが更新されます。
依存関係はlockファイルとあわせて管理されるため、個別にpipを実行する必要はありません。
[project]
name = "sample"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = [
"requests>=2.32.5",
]開発用のパッケージを追加したい場合は、–devオプションを使います。
uv add --dev pytestこの場合も、次のようにpyproject.tomlが更新され、開発用依存としてpytestが追加されます。
[dependency-groups]
dev = [
"pytest>=9.0.2",
]不要になったパッケージは、uv removeで削除します。
uv remove requests依存関係からrequestsが削除され、pyproject.tomlとlockファイルが更新されます。
pyproject.tomlは次のように依存関係が削除されます。
[project]
name = "sample"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []依存関係の同期・管理
環境を作り直したい場合や、lockファイルの内容に基づいて依存関係をそろえたい場合は、uv syncを使います。
uv syncこのコマンドを実行すると、lockファイルの内容に従って依存関係が同期されます。
よく使用するのが、別環境で同じ状態を作りたい時です。
uv syncを実行すると次のように.venvが作成されて必要なパッケージがインストールされます。
uv sync
Using CPython 3.13.9
Creating virtual environment at: .venv
Resolved 7 packages in 1ms
Installed 6 packages in 385ms
+ colorama==0.4.6
+ iniconfig==2.3.0
+ packaging==26.0
+ pluggy==1.6.0
+ pygments==2.19.2
+ pytest==9.0.2依存関係を再解決したい場合は、uv lockを使います。
uv lockこのコマンドにより、依存関係が再解決され、lockファイルが更新されます。
実行
Pythonの実行は、uv runを使います。
スクリプト実行、モジュール実行ともに同じ考え方です。
uv run python main.pyこの形で実行すると、プロジェクトの依存関係が反映された環境でPythonが実行されます。
モジュール実行の場合は、次のように書きます。
uv run python -m モジュール名pytestやフォーマッターなどのツールも、同様にuv run経由で実行します。
pytestを実行する場合、次のように実行します。
uv run pytestuv運用で迷いやすいポイント
uvを使っていると、pip installやvenv activateを使わなくてよいのか迷うことがあります。
しかし、uv addで依存を管理し、uv runで実行していれば問題ありません。
まとめ
uvを使ったPython開発では、最初に使うコマンドを決めておくことが重要です。
uv initで開始、uv addで依存を管理、uv runで実行することで覚えておけば、開発環境で何を使ったらよいのか迷うことはなくなります。
この記事が、uvコマンドを確認するための実務メモとして役立てば幸いです。
