uvの特徴 インストール ヘルプの見方 プロジェクト初期化 仮想環境上でPythonを実行する 仮想環境のPythonバージョンを切り替える ライブラリの追加 ライブラリの削除 依存関係を可視化 依存関係を一括インストール プロジェクトのバージョン管理 バージョン確認 バージョンアップ 参考資料
uvの特徴
- Python（仮想環境）のバージョン管理ができる
- 仮想環境へのライブラリのインストール、アンインストールができる
- 今までのパッケージ管理ツール（poetry）などと比較して非常に高速
- タスクランナーの機能はない
- 執筆時点ではバージョンが1.0になっていないため注意
インストール
Macの場合はHomebrewからインストールできる。
brew install uv■補完設定
任意だが、 .zshrcなどに補完設定をしておくと良い。
echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrcヘルプの見方
$ uv -h
An extremely fast Python package manager.
Usage: uv [OPTIONS] <COMMAND>
Commands:
run Run a command or script
init Create a new project
add Add dependencies to the project
remove Remove dependencies from the project
version Read or update the project's version
sync Update the project's environment
lock Update the project's lockfile
export Export the project's lockfile to an alternate format
tree Display the project's dependency tree
tool Run and install commands provided by Python packages
python Manage Python versions and installations
pip Manage Python packages with a pip-compatible interface
venv Create a virtual environment
build Build Python packages into source distributions and wheels
publish Upload distributions to an index
cache Manage uv's cache
self Manage the uv executable
help Display documentation for a command
Cache options:
-n, --no-cache Avoid reading from or writing to the cache, instead using a temporary directory for the duration of the operation [env: UV_NO_CACHE=]
--cache-dir <CACHE_DIR> Path to the cache directory [env: UV_CACHE_DIR=]
Python options:
--managed-python Require use of uv-managed Python versions [env: UV_MANAGED_PYTHON=]
--no-managed-python Disable use of uv-managed Python versions [env: UV_NO_MANAGED_PYTHON=]
--no-python-downloads Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]
Global options:
-q, --quiet... Use quiet output
-v, --verbose... Use verbose output
--color <COLOR_CHOICE> Control the use of color in output [possible values: auto, always, never]
--native-tls Whether to load TLS certificates from the platform's native certificate store [env: UV_NATIVE_TLS=]
--offline Disable network access [env: UV_OFFLINE=]
--allow-insecure-host <ALLOW_INSECURE_HOST> Allow insecure connections to a host [env: UV_INSECURE_HOST=]
--no-progress Hide all progress outputs [env: UV_NO_PROGRESS=]
--directory <DIRECTORY> Change to the given directory prior to running the command
--project <PROJECT> Run the command within the given project directory [env: UV_PROJECT=]
--config-file <CONFIG_FILE> The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=]
--no-config Avoid discovering configuration files (`pyproject.toml`, `uv.toml`) [env: UV_NO_CONFIG=]
-h, --help Display the concise help for this command
-V, --version Display the uv version
Use `uv help` for more details.プロジェクト初期化
以下のコマンドでプロジェクトを初期化できる。
uv init プロジェクト名# 実行例
$ uv init python-uv新しいディレクトリが作成され、自動でgit管理されるようになる。
$ tree python-uv
python-uv
├── main.py
├── pyproject.toml
└── README.md
1 directory, 3 files仮想環境上でPythonを実行する
uv run コマンドで仮想環境上でコマンドを実行できる。
main.pyを実行する場合は、以下のように記述する。
$ uv run python main.py
Hello from python-uv!仮想環境のPythonバージョンもわかる。
$ uv run python --version
Python 3.13.5仮想環境のPythonバージョンを切り替える
uv python pin バージョン3.13→3.12にPythonのバージョンをダウングレードしてみる。
$ uv python pin 3.12
error: The requested Python version `3.12` is incompatible with the project `requires-python` value of `>=3.13`. pyproject.tomlのバージョン制約を満たしていないと、上記のように怒られるので
ファイルを編集する。
# pyproject.toml
[project]
name = "python-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12" # 3.12以上の制約になるように修正
dependencies = []バージョンが切り替わっていることが確認できる。
$ uv python pin 3.12
Updated `.python-version` from `3.13` -> `3.12`
$ uv run python --version
Using CPython 3.12.11
Removed virtual environment at: .venv
Creating virtual environment at: .venv
Python 3.12.11ライブラリの追加
uv add ライブラリ名# requestsライブラリを追加する
$ uv add requests
Resolved 6 packages in 236ms
Prepared 1 package in 118ms
Installed 5 packages in 8ms
+ certifi==2025.7.14
+ charset-normalizer==3.4.2
+ idna==3.10
+ requests==2.32.4
+ urllib3==2.5.0 本番では使わないようなフォーマッタなどのライブラリは、 --devオプションを付けることで開発専用の依存関係としてインストールできる。
$ uv add --dev black
Resolved 13 packages in 4ms
Installed 6 packages in 6ms
+ black==25.1.0
+ click==8.2.2
+ mypy-extensions==1.1.0
+ packaging==25.0
+ pathspec==0.12.1
+ platformdirs==4.3.8[project]
name = "python-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
"requests>=2.32.4",
]
[dependency-groups]
dev = [
"black>=25.1.0",
]uvの特徴として、この辺のインストールが非常に高速である。
また、ライブラリはここから検索できる。
ライブラリの削除
uv remove requests依存関係を可視化
uv treeどのライブラリがどれに依存しているのかが一目瞭然。
$ uv tree
Resolved 13 packages in 1ms
python-uv v0.1.0
├── requests v2.32.4
│ ├── certifi v2025.7.14
│ ├── charset-normalizer v3.4.2
│ ├── idna v3.10
│ └── urllib3 v2.5.0
└── black v25.1.0 (group: dev)
├── click v8.2.2
├── mypy-extensions v1.1.0
├── packaging v25.0
├── pathspec v0.12.1
└── platformdirs v4.3.8依存関係を一括インストール
既に存在する uvを使ったプロジェクトをgit cloneしたときに
ライブラリを一括インストールしたい場合はこれ。
uv sync$ uv sync
Resolved 13 packages in 0.44ms
Prepared 11 packages in 259ms
Installed 11 packages in 7ms
+ black==25.1.0
+ certifi==2025.7.14
+ charset-normalizer==3.4.2
+ click==8.2.2
+ idna==3.10
+ mypy-extensions==1.1.0
+ packaging==25.0
+ pathspec==0.12.1
+ platformdirs==4.3.8
+ requests==2.32.4
+ urllib3==2.5.0プロジェクトのバージョン管理
バージョン確認
pyproject.tomlに記載されているバージョンを表示する。
$ uv version --short
0.1.0バージョンアップ
uv version --bump バージョンをどれくらい上げるかpatchバージョンを上げる場合は以下の通り。
$ uv version --bump patch
Resolved 13 packages in 345ms
Audited 11 packages in 0.01ms
python-uv 0.1.0 => 0.1.1minorバージョンを上げる場合は以下の通り。
$ uv version --bump minor
Resolved 13 packages in 5ms
Audited 11 packages in 0.00ms
python-uv 0.1.1 => 0.2.0