【uv使い方から仮想環境の削除まで】Pythonパッケージ管理の完全ガイド

最近では、pip の代わりに uv を導入する Python プロジェクトが急増しています。

たしかに pip は役割がシンプルで使い方も単純明快です。

でも仮想環境の構築には他のツールが必要だったり、依存関係の解決は開発者自身で行う必要がありました。

一方の uv、誤解を恐れずに表現するなら以下のような感じです。

pip + virtualenv + requirements.txt

これだけではなく「依存関係の自動調整」「超高速なパッケージ解決」まで担ってくれます。

Rust 製ということもあり、pip に比べて 10〜100倍以上高速 なのが最大の強みです。

使い始めると超便利なものの、まだ日本語情報が少ないのも事実です。

そこで、本記事は以下の内容をお伝えします。

最初こそ pip との違いに戸惑いますが、いざ使ってみると pip には戻れないほどに便利なツールです。

本記事で uv の基本的な使い方をマスターしていきましょう！

uv ってどんなもの？

まずは、uv の概要を解説します。

多機能なのでどんな役割があるのかを理解するのが先決です。

また、この段階で uv が管理する２つのファイルを知っておきましょう。

そもそも、uv って何？

uv は以下の機能を提供します。

一方で、pip は「パッケージのインストール」に特化したツールです。

通常は pip 単体で使うことはまれで、仮想環境を構築するためには別コマンドを使ったり、依存関係の管理を行うために requirements.txt を併用する必要があります。

uv は pyenv + pip + virtualenv + requirements.txt を一本化したツール とも言えます。
しかも Rust 製なので動作が圧倒的に速い。

ここからは uv のメリットを少し掘り下げて解説します。

パッケージの管理

pip と同様にパッケージ管理が行えます。

これだけ見ると pip との差はないようにも思えます。

ところが、次から説明する「仮想環境の管理」と「依存関係・互換性の調整」という機能を知ると、uv を使うメリットが分かっていただけると思います。

仮想環境の管理

uv を使うと、そのプロジェクト固有の仮想環境が自動的に構築されます。

uv sync や uv add を実行するだけで、プロジェクトルートに .venv が自動生成されます。

これにより異なるプロジェクト間でライブラリのバージョンの衝突をさけ、環境を隔離して安全に作業できるようになります。

Python バージョンの管理

uv は Python のインストールと切り替えも内蔵 しています。

従来は pyenv を別途インストールする必要がありましたが、uv だけで完結します。

uv python install 3.11
uv python pin 3.11

uv python install 3.11
uv python pin 3.11

依存関係・互換性の調整

一般的なプロジェクトでは、複数のパッケージを利用することがほとんどだと思います。

そこで問題になるのが、依存関係・互換性の問題です。

異なるパッケージが、ある特定のパッケージの別バージョンを求めることがあります。

例えば pandas と scikit-learn はともに NumPy が必要です。
pandas が NumPy の 1.19 以降を要求している一方で、scikit-learn は NumPy の 1.18 以降を要求しているとします。

この場合には NumPy の 1.19 以降をインストールしないといけません。

pip の場合は開発者が requirements.txt の中身を目視で確認して、各パッケージのインストールすべきバージョンを決めていくという作業が必要でした。

uv を導入するだけで、これまで人間が目視で行っていた依存関係の調整を自動化できます。
しかも従来のツールより大幅に高速です。

uv が管理する２つのファイル

uv では、以下の２つのファイルが生成されます。

この２つの組み合わせで、requirements.txt の役割を果たします。

pyproject.toml

uv add コマンドでパッケージを追加すると、pyproject.toml ファイルが更新されます。

このファイルでは、プロジェクトの依存パッケージとそのバージョンの「範囲」を定義します。

pyproject.toml はパッケージを「インストール」するわけではなく、あくまで依存関係を「宣言」するだけです。

uv.lock

パッケージの依存関係を解決し、具体的なバージョンを固定するために、uv.lock ファイルが使用されます。

pyproject.toml に基づいて依存関係の解決が行われた後（例えば uv sync コマンド実行時に）、uv はこの解決結果を uv.lock に記録します。

これにより、インストールされるパッケージのバージョンが確定されます。

Poetry との違い
Poetry の poetry.lock に相当するのが uv.lock です。
形式は異なりますが役割は同じです。

uv のインストール方法

uv の大きなメリットのひとつが、pyenv が不要な点です。uv 自体が Python バージョン管理機能を内蔵しているため、インストール手順がシンプルになります。

uv のインストール

以下のコマンドを実行するだけでインストールできます。

macOS / Linux の場合

curl -LsSf https://astral.sh/uv/install.sh | sh

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows の場合

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

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

インストール後、シェルを再起動するか以下を実行してパスを反映します。

source ~/.zshrc  # zsh の場合
source ~/.bashrc  # bash の場合

source ~/.zshrc  # zsh の場合
source ~/.bashrc  # bash の場合

インストールの確認は以下のコマンドで行います。

uv --version

uv --version

uv 0.x.x のようなバージョンが返ってくれば完了です。

Python のインストール（uv で完結）

uv を使って Python をインストールします。pyenv は不要です。

インストールできる Python のバージョン一覧を確認します。

uv python list

uv python list

インストールしたいバージョンが決まったら以下を実行します。
ここでは 3.11 をインストールしてみます。

uv python install 3.11

uv python install 3.11

システム全体で使う Python のバージョンを固定する場合は以下のコマンドを実行します。

uv python pin 3.11

uv python pin 3.11

uv の使い方：パッケージ管理編

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

ライブラリのインストールは、以下のコマンドを実行します。

uv add パッケージ名

uv add パッケージ名

上記を実行すると、pyproject.toml にインストールしたライブラリ名とバージョンが追記され、uv.lock も自動更新されます。

pip だと pip freeze が必要でした。
uv ならパッケージ追加時に pyproject.toml への追記を自動で行なってくれるので、管理がとても楽です。

開発中だけ使うライブラリのインストール

本番環境では使わないパッケージは、--dev オプションをつけると便利です。

uv add パッケージ名 --dev

uv add パッケージ名 --dev

こうしておくと、pyproject.toml の [dependency-groups] セクションに開発中のみ使うパッケージとして記録されます。

本番環境のインストール時には、以下のコマンドを実行します。

uv sync --no-dev

uv sync --no-dev

これで --dev オプションをつけたパッケージはインストールされません。

プロジェクトをクローンした場合のライブラリインストール

プロジェクトをクローンした直後にはパッケージが何も入っていないので、以下のコマンドでパッケージを一括インストールします。

uv sync

uv sync

本番環境で、開発時のみに利用するパッケージをインストール対象から除外したい場合は、以下のコマンドを実行します。

uv sync --no-dev

uv sync --no-dev

pip install -r requirements.txt と同じような挙動になります。

パッケージの削除

パッケージの削除は、以下のコマンドを実行します。

uv remove パッケージ名

uv remove パッケージ名

パッケージのアップデート

すべてのパッケージをアップデートするには、以下のコマンドを実行します。

uv lock --upgrade

uv lock --upgrade

特定のパッケージだけをアップデートする場合は以下のコマンドを使います。

uv lock --upgrade-package パッケージ名

uv lock --upgrade-package パッケージ名

ロックファイルを更新したあとに uv sync で反映します。

uv sync

uv sync

--upgrade はすべての依存パッケージを最新版に更新しようします。
メジャーバージョンアップによる破壊的変更が含まれる場合があるので、本番環境で実行する際はアップデート後に動作確認を行いましょう。

uv の使い方：仮想環境編

仮想環境の作成

uv では、uv sync や uv add を実行した時点でプロジェクトルートに .venv が自動生成されます。

明示的に仮想環境だけを作成したい場合は以下のコマンドを使います。

uv venv

uv venv

特定の Python バージョンで仮想環境を作成する場合は、オプションで指定します。

uv venv --python 3.11

uv venv --python 3.11

Poetry との違い
Poetry では poetry config virtualenvs.in-project true で仮想環境をプロジェクトルートに作成する設定が必要でしたが、uv はデフォルトでプロジェクトルートに .venv を作成します。

使用する Python バージョンの選択

プロジェクトで使う Python バージョンを固定するには、以下のコマンドを実行します。

uv python pin 3.11

uv python pin 3.11

これにより .python-version ファイルが生成され、そのプロジェクトで使う Python バージョンが固定されます。

対象のバージョンの Python がまだインストールされていない場合は先にインストールしてください。

uv python install 3.11

uv python install 3.11

仮想環境の削除

誤って仮想環境を作成してしまった場合などは、.venv ディレクトリを削除するだけです。

rm -rf .venv

rm -rf .venv

削除後に uv sync を実行すれば、クリーンな状態から再セットアップできます。

仮想環境に入る

仮想環境に入るには、次のコマンドを使います。

macOS / Linux

source .venv/bin/activate

source .venv/bin/activate

Windows

.venv\Scripts\activate

.venv\Scripts\activate

Poetry との違い：Poetry では poetry shell という専用コマンドがありましたが、uv では標準的な source .venv/bin/activate を使います。

仮想環境から抜ける

仮想環境から抜けるには、以下のコマンドを実行します。

deactivate

deactivate

これにより仮想環境が非アクティブになり、システムのグローバルな Python 環境に戻ります。

プロジェクトのセットアップ

これからプロジェクトを立ち上げる場合は uv init を実行します。

新しいディレクトリを作ってプロジェクトを始める場合：

uv init プロジェクト名

uv init プロジェクト名

すでに存在するディレクトリを uv 管理下に置く場合：

cd プロジェクトのディレクトリ
uv init

cd プロジェクトのディレクトリ
uv init

uv init を実行すると、以下のファイルが自動生成されます。

pyproject.toml ファイルの書き方

uv では pyproject.toml の [project] というセクションにプロジェクトの詳細を書き込みます。

これは uv init コマンドを実行した時に生成される項目です。

本セクションでは、[project] セクションに書く内容を解説します。

name

プロジェクトをあらわすような、わかりやすい名前をつけます。

[project]
name = "my_blog"

[project]
name = "my_blog"

仮に PyPI などのパッケージリポジトリに公開する時はこの name が識別子になるので、他のパッケージと重複しないように名前をつける必要があります。

とはいえ、個人開発で PyPI などに公開しないのであればわかりやすい名前をつけるで大丈夫です。

PyPI に公開する場合は注意：PyPI ではこの name が識別子になっているので、他のパッケージと重複を避ける必要があります。

version

プロジェクトのバージョンを記載します。

プロジェクトの更新のたびにバージョンを上げていく必要があり、一般的にはセマンティックバージョニングと呼ばれる管理を行います。

[project]
version = "1.2.3"

[project]
version = "1.2.3"

それぞれの桁ごとの意味合いは以下の通りです。

なおプレリリースやビルドメタデータを含めることもできるので、1.2.3-a1 といった書き方でも大丈夫です。

description

プロジェクトの説明を簡潔に書きます。

[project]
description = "A robust and user-friendly blog system designed for both individual bloggers and enterprise-level content management."

[project]
description = "A robust and user-friendly blog system designed for both individual bloggers and enterprise-level content management."

書き方のポイントは以下の通りです。

license

ライセンスを記述します。

[project]
license = { text = "MIT" }

[project]
license = { text = "MIT" }

例えば次のようなライセンスを設定します。

authors

プロジェクトの作成者を記述します。

[project]
authors = [
    { name = "Steive", email = "sample@gmail.com" },
]

[project]
authors = [
    { name = "Steive", email = "sample@gmail.com" },
]

形式は { name = "名前", email = "メール" } の形式で指定してください。

maintainers

保守を行う人がいれば、記述します。

[project]
maintainers = [
    { name = "Emily", email = "sample@gmail.com" },
    { name = "Bob", email = "sample@gmail.com" },
]

[project]
maintainers = [
    { name = "Emily", email = "sample@gmail.com" },
    { name = "Bob", email = "sample@gmail.com" },
]

プロジェクトのオーナー以外にメンテナンスを行う人を分けて書いておけるのは便利です。

readme

README ファイルへのパスを記載する場所です。

[project]
readme = "README.md"

[project]
readme = "README.md"

一般的に README ファイルには以下のような事項が書かれます。

urls [ オプション ]

ホームページ・リポジトリ・ドキュメントの URL は [project.urls] セクションにまとめて記述します。

[project.urls]
Homepage = "https://www.sample.com"
Repository = "https://github.com/~~~"
Documentation = "https://sample.com/docs"

[project.urls]
Homepage = "https://www.sample.com"
Repository = "https://github.com/~~~"
Documentation = "https://sample.com/docs"

参考サイト