🐶

UVまとめ

2025/11/29に公開

Python

tech

※UV利用の際は、公式ドキュメントも合わせてを参照すること
※本記事は、個人用のメモだが、必要に応じて今後も更新を行う

UV - Python Package Managerまとめ

PythonのパッケージマネージャであるUVについてまとめている。

UVとは

UVは、Astral社が開発しているRust製のPythonパッケージマネージャ。
2025年現在、徐々にシェアを伸ばしており、開発も非常に盛んなツール。

特徴

軽量/高速： PyenvやPipenv等と比較して、高速に動作する
ワンストップ： ライブラリや仮想環境だけでなく、Python自体の管理もこれ一本で行える
低学習コスト： 公式ドキュメントがしっかり書かれており、キャッチアップし易い

導入手順

代表的なインストール方法のみ記載（以下に記載の無い手順については、公式サイトを参考）

Homebrew

brew install uv

PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

pip

pip install uv

WinGet

コマンドプロンプトなどで、以下を実行

winget install --id=astral-sh.uv  -e

使い方

代表的な用途に絞り、用途を記載。

Pythonのインストール

バージョンを指定して導入する場合

uv python install 3.13.5

※v3.13.5をデフォルト利用するバージョンとしたい場合は、--defaultをオプションを付与

uv python install 3.13.5 --default

インストールされているPythonの一覧表示

uv python list --only-installed

プロジェクトの作成

UVでは、Pythonの作業単位をプロジェクトと呼び、pyproject.tomlをプロジェクトのトップ階層に作成して管理する。

プロジェクトの情報（名称・バージョン）
Pythonのバージョン
依存関係（ライブラリ一覧）
その他ツールや実行コマンドなど

プロジェクトを一から作成する場合

your-project-nameディレクトリを作成し、その中に利用する各種ファイルを生成する。

uv init your-project-name

Pythonのバージョンを指定してプロジェクト作成する場合

uv init your-project-name --python 3.13

既に存在するディレクトリをUVプロジェクト化する場合

UVプロジェクトとして管理したいディレクトリのトップ階層で、以下を実行

uv init

※既存ディレクトリ内にUVで利用するファイル群が作成される

UVプロジェクトの主な構成要素

uv initを実行すると以下のファイル群が作成される。

/
├ .venv              → プロジェクト用の仮想環境データ
├ .python-version    → 使用するPythonバージョンを示す(uv venv実行時等に参照される)
├ .gitignore         → Git用の無視リスト
├ main.py            → 動作確認用のmainファイル
├ README.md          → 本プロジェクトのドキュメント
├ pyproject.toml     → プロジェクト名、バージョン、依存ライブラリ等を管理するコアファイル
└ uv.lock            → 依存関係のロックファイル(ライブラリの厳密な依存関係を示す)

pyproject.tomlの中身

一般的なpyproject.tomlは以下の構造となっている。

[project]
name = "your-project-name"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []

[dependency-groups]
dev = []

name: プロジェクトの名称
version: プロジェクトのバージョン
description: プロジェクトの概要説明文
readme: プロジェクトのREADMEファイル
requires-python: プロジェクト実行に必要なPythonバージョン
dependencies: 依存するライブラリ群(後続のライブラリのインストールを行うと記載される)
[dependency-groups] dev: 依存する開発用ライブラリ群

ライブラリ管理

UVを用いてプロジェクトで利用するライブラリを管理する手順

ライブラリのインストール

最新版を導入する場合
```
uv add ライブラリ名
```
requestsを導入する場合の例:

uv add requests
特定のバージョンを導入する場合
```
uv add ライブラリ名==バージョン
```
requestsのv2.31.0を導入する場合の例:

uv add 'requests==2.31.0'
開発時のみ利用するライブラリを導入する場合
```
uv add ライブラリ名 --dev
```
pytestとpytest-covを導入する場合の例:

uv add pytest pytest-cov --dev
requirements.txtから導入する場合
pip用ライブラリ管理ファイルのrequirements.txtがプロジェクト内に存在しており、そこで管理されているライブラリをuvで導入する場合
```
uv add -r requirements.txt
```

ライブラリのアンインストール

インストール済のライブラリをアンインストールする手順

uv remove ライブラリ名

requestsをアンインストールする場合の例:

uv remove requests

特定ライブラリのバージョンを更新

特定のインストール済ライブラリを更新する手順

uv lock --upgrade-package ライブラリ名

requestsを更新する場合の例:

uv lock --upgrade-package requests

全ての依存関係を更新

pyproject.tomlに記述されたバージョン制約(>=1.0.0等)の範囲内で更新
```
uv sync --upgrade
```
pyproject.tomlのバージョン制約を超えて更新
uvには、一括で最新版に書き換えるコマンド（例: npm update --saveのようなもの）は未実装である為、uv addコマンドで、インストール済ライブラリを再指定する必要がある
例: langchainとpydanticを最新版にする場合
```
uv add langchain pydantic
```

既存プロジェクトから同期

既にpyproject.tomlやuv.lockを作成済のプロジェクトと同期し、同じライブラリ・依存関係を持つ仮想環境を構築する手順

uv sync

uvプロジェクト管理内容をrequirements.txtへ反映

UVプロジェクトとして管理しているライブラリ・依存関係をrequirements.txtへ反映する

uv pip compile pyproject.toml > requirements.txt

コードの実行

Python REPL起動

Pythonコマンドを実行してreplを起動したのと同じ状態となる。

uv run python

Python 3.13.5 (main, Jul 23 2025, 00:30:06) [MSC v.1944 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
＞＞＞

Pythonファイルの実行

Pythonファイルを指定して事項する。

uv run example.py

インストールしたツール実行の例

uv run pytest . --cov
uv run ruff check .

UV自体の更新・削除

UVの更新

スタンドアローンインストーラー（公式スクリプト）でインストールしている場合
```
uv self update
```
pipで全体インストールしている場合
```
pip install -U uv
```

以上。