Python パッケージ管理ツール「uv」とは？ – 爆速のライブラリ管理を初心者向けに解説

Python で開発を始めるとき、パッケージ管理や仮想環境という言葉を耳にすることが多くなります。特に最近注目されているのが、Rust 製の超高速パッケージ管理ツール「uv」です。この記事では、Python 初心者の方向けに「uv」とは何か、なぜ便利なのかをわかりやすく解説します。

詳細を確認する

uv の魅力

そもそもなぜ uv を使って仮想環境を管理するのが良いか、結論から先に述べておきます。

• 従来のパッケージ管理システムであるpipと比べて圧倒的に早い
• プロジェクト用のディレクトリを作って仮想環境を作成する、などの定型作業を簡略化できる

例えば yfinance ライブラリのインストールでは uv は約3秒、従来の pip は約 10秒と3倍以上の差が出ます。

↓ uv add を使った場合

↓ pip install を使った場合

普段pipを使ってパッケージ管理しているという方も、この機会にぜひuvを使った仮想環境管理を始めてみてください。

そもそも仮想環境って何？ – プロジェクトごとの“部屋”を作ろう

uv の話に入る前に、初心者の方がつまずきやすい「仮想環境」について簡単に説明します。

Python の大きな魅力の一つに、サードパーティーライブラリが充実している、というものがあります。サードパーティーライブラリとは、Python インストール時に一緒にインストールされるライブラリとは別の、第三者が開発し公開しているライブラリのことです。例えば、requestsやpandasなどはサードパーティーライブラリの代表的な例です。

このサードパーティーライブラリを使う場合は、その都度インストールして使いますが、仮想環境を使わないでインストールすると問題が起きてしまいます。そのため、仮想環境を使ってサードパーティーライブラリをインストールするのが基本的な Python の作法です。

仮想環境とは、一言で言えば「プロジェクトごとに分離された専用の Python 環境」のことです。通常、Python で仮想環境を使わずにライブラリをインストールすると、システム全体（またはユーザー全体）で共有されます。しかしこの場合、別々のプロジェクト間でライブラリのバージョンがぶつかったり、不必要なものまで混ざってしまったりしてトラブルの元になります。

なぜなら、プロジェクト A ではrequestsのバージョン 1.0 にしなければならないが、プロジェクト B ではrequestsのバージョン 2.0 でなければならない、ということがあります。ところがシステム全体にインストールしたrequestsがバージョン 1.0 だとプロジェクト B では要件を満たさなくなり、エラーが出てしまいます。

いってみれば、複数のエンジニアが、1台のパソコンを取り合っているような状況です。

このような場合に仮想環境を使うと、プロジェクト A 用、プロジェクト B 用…といった具合にそれぞれ独立したライブラリの置き場を作れるのです。

例えて言うなら、仮想環境はプロジェクト専用の部屋（またはサンドボックス） です。各部屋にはそのプロジェクトに必要な道具（ライブラリ）だけが置いてあり、他の部屋の道具とは混ざりません。

仮想環境を使うことで、「他のプロジェクトで動いていたコードが急に動かなくなった…」といった依存関係の混乱（いわゆる“依存関係地獄”）を避けることができます。Python 開発において仮想環境は今や必須の知識ですので、uv を使わない場合でも是非覚えておきましょう。

uv の基本的な使い方 – インストールからプロジェクト作成まで

では本題のuv の使い方を見ていきます。ここでは Windows および Mac で Python 3.13 を使っていることを想定します。uv 自体のインストール方法から、プロジェクトでライブラリを追加する手順まで、順を追って解説します。

uv のインストール方法

uv は以下の方法でインストールできます。初心者の方には手軽な方法として、まず公式の一行インストールスクリプトを使う方法をおすすめします。

Windows の場合

PowerShell を管理者権限で起動して次のコマンドを実行します。

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

Mac の場合

ターミナルで次のコマンドを実行します（公式サイトが提供するスクリプトを実行する形です）。

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

brew を使う場合は以下のコマンドを実行します。

brew install uv

インストール成功の確認

インストール後にターミナルを再起動し、uv --versionやuv helpを実行してみて、エラーが出なければ導入成功です。

uv -V
uv 0.6.14 (Homebrew 2025-04-09)

プロジェクトの初期化（uv init）と仮想環境の作成

uv をインストールできたら、早速プロジェクトで使ってみましょう。まず新しく Python プロジェクトを始める場合や、既存プロジェクトで uv 管理に切り替える場合は、プロジェクト用フォルダでuv initを実行します。

ここでは uv_testというディレクトリ(フォルダ)を作成し、作業を進めていきます。

mkdir uv_test
cd uv_test

続いて、uv initを実行することで、カレントディレクトリに以下のファイルが作成されます。

uv init

lsコマンドで確認してみてください。

Windows (PowerShell)

ls -Force

Mac

ls -la

作成されたファイル、フォルダ群

すると以下のファイルが作成されていることがわかります。先頭にドットが付いているものは隠しファイルや隠しディレクトリです。-Forceや-laは、隠しファイルも表示するようにするオプションです。

.git
.gitignore
.python-version
README.md
main.py
pyproject.toml

• .git – Git リポジトリのディレクトリ(バージョン管理に用いる)。
• .gitignore – Git で無視するファイルの設定。
• .python-version – Python バージョン管理。
• README.md – プロジェクトの説明文。
• main.py – サンプルの Python コードで、プロジェクトが空の場合に雛形として用意されるものです。削除しても構いません。
• pyproject.toml – プロジェクトの設定ファイル（後述）。

このように、uv initは複数のファイル・ディレクトリを一度に作成できます。冒頭で述べた「定型作業を簡略化」の一例です。

プロジェクト用ディレクトリまで一気に作成するコマンド

上述のように、プロジェクトフォルダ作成と init コマンドを別々に実行するのではなく、以下のようにすれば、プロジェクト用フォルダと上述のファイル・ディレクトリ群を同時に作成できます。

uv init <プロジェクト名>

uv initにより、仮想環境（.venv フォルダ）も自動で作成されるといわれていますが、本稿執筆時点の最新バージョン 0.6.14 では、仮想環境は手動で作成する必要があります。もっとも、後述するuv addを使えば、仮想環境も同時に作成できますので、以下のコマンドは実行する必要はありません。

uv venv <仮想環境名>

具体的には

uv venv .venv

とすると、次のような出力が表示されます(Mac の場合)。

Using CPython 3.13.2
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

続けて、Activate with: の後に書かれているコマンド（source .venv/bin/activate または .venv\Scripts\activate）で仮想環境を起動しましょう。

パッケージ（ライブラリ）の追加: uv add と uv sync

仮想環境の準備ができたので、次にライブラリを入れてみましょう。従来ならpip install ライブラリ名でインストールしていたところですが、uv では専用コマンドuv addを使います。例えば、プロジェクトに WEB フレームワークdjangoを入れたい場合

uv add django

と実行します。すると、uv は以下のような処理を自動で行います。

• 適切な Python インタプリターで仮想環境(.venv)を作成（仮想環境がない場合）。
• PyPI 上からdjangoおよびその依存ライブラリを解決し、必要なパッケージ一覧を決定。
• パッケージのダウンロード・インストールを実行。

実行結果として、「X 個のパッケージを何ミリ秒で解決」「Y 個のパッケージを準備・インストール」などと表示され、例えばdjangoに加えてasgirefやsqlparseなどの関連ライブラリも含め数秒以内で完了します。

uv add django
Using CPython 3.13.2
Creating virtual environment at: .venv
Resolved 5 packages in 4ms
Prepared 3 packages in 1.12s
Installed 3 packages in 59ms + asgiref==3.8.1 + django==5.2 + sqlparse==0.5.3

このとき従来の pip installのようにあらかじめ仮想環境を作成し、仮想環境に入っておく必要はありません。「仮想環境に入り忘れたままpip installを実行してしまい、システム全体にインストールしてしまった！」という初心者あるあるを避けられます。もちろん、あらかじめ仮想環境を作成・仮想環境に入った状態でuv addを実行しても構いません。

ただ、仮想環境にインストールしたライブラリを使ったプログラムを実行するには、仮想環境に入った状態でプログラムを実行する必要があります。後述のuv runコマンドを用いれば一時的に仮想環境を起動してプログラムを実行できます。

が、仮想環境が有効になるのはその一回限りなのでやはり .venv\Scripts\activate (Windows) もしくは source .venv/bin/activate (Mac) で常に仮想環境に入った状態にしておくのがおすすめです。

（補足）uv は初めてuv addを実行したタイミングで自動的にpyproject.tomlファイルにそのライブラリを追加し、依存関係をまとめたuv.lockファイルも生成・更新します。これらについては後述します。

その他の基本コマンド (remove, sync, lock, run, tree)

uv には他にも便利なコマンドが用意されています。主なものをまとめると次の通りです。

• uv remove <ライブラリ名> – プロジェクトからライブラリを削除します。依存関係から外し、仮想環境からもアンインストールされます。
• uv sync – プロジェクトの依存関係設定（pyproject.toml や lock ファイル）と仮想環境の内容を同期します。レポジトリをクローンしてプロジェクトを構築する際などに使用します。
• uv lock – 依存関係のロックファイル（uv.lock）を生成・更新します。通常uv add時に自動実行されますが、明示的にロックだけ更新したい場合に使います。
• uv run <コマンド> – 仮想環境上で指定したコマンドを実行します。例えばuv run pytestとすれば、そのプロジェクトの環境で pytest（テスト）を実行できます。uv run pythonとすれば仮想環境の Python で対話モードを起動でき、プログラムもその環境で動かせます。
• uv tree – プロジェクトの依存関係ツリーを表示します。どのパッケージがどのパッケージに依存しているかを階層表示するコマンドで、環境の把握に役立ちます。

まずは以上のコマンドを覚えておけば、ひと通り uv での開発を進められるでしょう。pip で行っていた操作は、基本的にuv <サブコマンド>で代替できるイメージです。次は、従来の pip コマンドとの具体的な違いに触れてみます。

従来の pip install と何が違うの？

uv を使うときに気になるのが、「従来のpip installと何が違うのか」という点ですよね。ここでは処理方式や使い勝手の違いをもう少し詳しく見てみましょう。

pip コマンドとの互換性と違い

uv は「pip のドロップインリプレース（置き換え）」を目指して作られており、pip の主要な機能はほぼそのまま使える互換モードを持っています。例えば、以下のような pip コマンド相当の操作が uv でも可能です。

uv pip install <パッケージ名>

pip installと同様、パッケージをインストール。ただし仮想環境が存在しないとエラーになります

uv pip install -r requirements.txt

pip install -rと同様、requirements.txt の内容をまとめてインストール

uv pip uninstall <パッケージ名>

pip uninstallと同様、パッケージをアンインストール

uv pip list

インストール済みパッケージの一覧表示（pip listと同様）

uv pip freeze

インストール済みパッケージをpip freeze形式で表示

互換性の違い

このように、基本的な pip 操作は uv 経由でも同じように実行可能です。そのため、既存のプロジェクトに uv を導入しても、慣れ親しんだ pip コマンド感覚で操作できます（実際は内部で uv の速い処理が動いています）。

では一方で、uv 独自の違いとして何があるでしょうか？主なポイントは次の通りです。

• 圧倒的な速度: すでに述べた通り、uv は pip に比べて数倍～数十倍の速度で依存関係の解決とインストールを行います。Rust 製実装の恩恵で公式ベンチマークでは最大 100 倍速いとされます。
• 一部の挙動の違い: uv は pip との互換性を重視しつつも、依存関係の解決アルゴリズムが独自実装のため、場合によって pip と異なるバージョンのパッケージを選択することがあります。例えば、あるライブラリがまだ正式版でなくプレリリース版（ベータ版など）しかない場合、pip はそれを入れてしまうことがありますが、uv は極力安定版（ステーブル）を選ぶポリシーを持っています。そのため、同じコマンドでも pip 経由と uv 経済由で入るバージョンが異なるケースがありえます。ただし大半の一般的なケースでは気にしなくてよい差異であり、uv 側でも将来の互換性改善が議論されています。
• 環境の一元管理: pip はあくまで「パッケージインストールツール」で、仮想環境作成にはvenv、依存関係のロックにはpip-toolsやPoetryなど他のツールが必要でした。uv は単体でプロジェクトの仮想環境作成からパッケージ管理、Python 本体の切替、ロックファイル管理まで対応しています。つまり uv 一つで、従来は pip ＋ venv ＋ pip-tools（または Poetry/Pipenv）＋ pyenv…と複数併用していた機能をカバーできる統合ツールです。初心者にとっても、複数ツールを覚える必要が減るのはメリットでしょう。

総じて、uv は「中身はまったく新しいけれど、表向きは pip ライク」な存在と言えます。既存のワークフローになじませやすく、なおかつ性能が劇的に向上するため、試してみる価値は大いにあります。

uv 特有のファイル – pyproject.toml と uv.lock の意味

uv を使うと、プロジェクトフォルダ内に見慣れないファイルが生成されます。それがpyproject.tomlとuv.lockです。それぞれ役割がありますので押さえておきましょう。

• pyproject.toml: これは Python のプロジェクトの設定を記述するためのファイルです。元々 PEP（Python Enhancement Proposal）で定められた従来の設定ファイルで、プロジェクト名やバージョン、依存ライブラリの一覧などを記載します。uv ではpyproject.toml内の[project]セクションにdependencies（依存関係）としてライブラリ名とバージョン指定が追記されていきます。例えば先ほどuv add pytestを実行した場合、pyproject.toml の中にdependencies = ["pytest"]のような行が追加されます（実際はバージョン指定も含まれます）。要するに、プロジェクトで必要なライブラリを宣言するファイルであり、Poetry など他のツールでも用いられる共通フォーマットです。
• uv.lock: こちらはロックファイルと呼ばれるものです。簡単に言えば、「このプロジェクトで実際にインストールしたすべてのパッケージとそのバージョンを記録したスナップショット」のようなファイルです。uv ではuv addやuv lock実行時に自動的にuv.lockが生成/更新され、そこに直接・間接すべての依存パッケージとその正確なバージョン、ハッシュ値などが書き込まれます。例えばpytestを追加した場合、pytest 本体のバージョンだけでなく、その依存であるpluggyやpackaging等のバージョンもすべて記録されます。

ロックファイルがあることで、チーム開発や将来の環境再現が容易になります。全員が同じバージョンの組み合わせで開発できるため、「ある人の環境では動くのに別の人の環境では動かない」という事態を防げます。また、一度決まった組み合わせを次回からそのまま使えるので、毎回依存解決をやり直す必要がなくインストールがさらに高速になります。

uv.lock は手動で編集する必要はなく、むしろ内容を人間が細かく把握する必要もありません（長大な一覧になります）。重要なのは、このファイルをGit などバージョン管理に含めて共有することです。こうすることで、別の開発者がリポジトリをクローンしてuv syncするだけで、全く同じ環境が復元されます。

requirements.txt との違い

Python で依存関係を記録・共有する方法としては、昔からrequirements.txtというファイルもよく使われてきました。これは単にライブラリ名==バージョンを羅列したテキストファイルで、pip install -r requirements.txtでそのリストのパッケージをインストールできるものです。uv.lock と requirements.txt は目的が似ていますが内容の詳細さに違いがあります。

• uv.lock は上記のようにすべての依存関係（transitive dependencies も含む）と正確なバージョン、ハッシュ値等を記録した詳細なファイルです。環境を再現することに特化しており、開発時の再現性・安定性を担保します。
• requirements.txt は基本的に直接依存のパッケージのみを列挙する場合が多く、シンプルですが詳細な依存ツリーまでは含みません。その分、pip やその他のツールでも幅広く扱える互換性の高い形式です。

uv を使って開発する際は原則 uv.lock を使えば十分ですが、例えばデプロイ環境で uv が使えない場合や、他のサービス（CI ツールなど）が requirements.txt しか受け付けない場合もあるでしょう。そんなときのために、uv にはuv export -o requirements.txtというコマンドが用意されており、現在の uv.lock の内容からピン留め（固定）されたバージョン一覧を requirements.txt 形式で出力できます。

このようにして作った requirements.txt を使えば、uv を直接使わない環境でも同じパッケージ群をインストールできます。ただし基本的には、開発・テストでは uv.lock を使い、必要に応じて出力した requirements.txt は配布や一時的な用途に留めるのがよいでしょう。

uv 利用上の注意点 – pip との併用に要注意！

最後に、uv を使う上での注意点や初心者がハマりがちなポイントをいくつか紹介します。便利な uv ですが、使い方を誤ると思わぬ混乱を招くこともありますので気をつけましょう。

pip コマンドを直接使わない（uv 経由で使う）

uv 導入後に最も陥りがちなのは、うっかり従来どおりにpip installコマンドを実行してしまうケースです。例えば仮想環境を有効にしていない状態でpip install XXXとしてしまうと、それはシステム全体にインストールされてしまい、uv 管理の環境には反映されません。逆に仮想環境が有効な状態で pip コマンドを直に使うと、ライブラリ自体は仮想環境に入りますがuv の lock ファイルや設定は更新されないため、実際の環境と uv.lock との内容がズレてしまう可能性があります。この「依存関係のズレ」が起きると、後でuv syncしたときに余計なパッケージが削除されたり、逆に存在しないはずのパッケージが残ってuv treeに表示されない等、混乱のもとになります。

要するに、uv を使い始めたら、パッケージの追加・削除には必ず uv 経由のコマンドを使う習慣をつけましょう。インストールならuv addまたはuv pip install、アンインストールならuv removeまたはuv pip uninstallといった具合です。pip の実行をすべて uv に仲介させることで、uv 側で状況を正しく把握でき、lock ファイルも正確に保たれます。

万一、「uv を付け忘れて pip コマンドを実行してしまった！」という場合の対処法も覚えておきましょう。一番確実なのは、仮想環境内からそのパッケージを削除して環境をクリーンに戻すことです。具体的には:

pip freeze > uninstall.txt # 仮想環境内の全パッケージ一覧を出力
pip uninstall -r uninstall.txt -y # その一覧に載っているパッケージを一括アンインストール

とする方法があります。この手順で仮想環境を一度まっさらにしてから、改めてuv syncを実行すれば、uv.lock に基づいて正しい状態に復元できます（いったん環境をリセットし、uv.lock→ 環境を同期し直すイメージです）。実際、pip には-rオプションで一覧に記載のパッケージをまとめて削除する機能があり、上記のようにpip freezeの結果を使うことで「インストールされているものを全部消す」ことが可能です。この操作は強力なので、他に影響が出ないか注意しつつ自己責任で行ってください。

uv コマンドと仮想環境の関係

uv はuv runコマンドを使うことで、仮想環境を自動で利用してコマンドを実行できます。例えば、前述のuv run pytestでは、仮想環境を有効化した状態で pytest を走らせてくれます。これは便利な反面、直接仮想環境をアクティベートして作業する場合との挙動の違いに注意しましょう。

通常、仮想環境を使う場合はsource .venv/bin/activate（Windows では.\.venv\Scripts\activate）を実行してから作業します。uv ではuv runを使えば activate しなくてもよいのですが、対話的に仮想環境に入って作業したい場合は従来通り activate しても構いません。activate してしまえば、あとの操作は普通の pipenv などと同じ感覚で、pythonコマンドやpip list等も仮想環境上で動きます。ただし先述の注意 ➀ の通り、activate 中でも新たなパッケージ追加はuv addで行うようにしてください（pip を直接使うと uv に情報が行かない点は同じです）。

また、uv が作る仮想環境の名前にも触れておきます。デフォルトでは.venvフォルダに仮想環境を構築しますが、uv venv <フォルダ名>コマンドで別名の環境を作ることもできます。しかしその場合、環境を activate しないとuv pip系コマンドがうまく動作しないという現象が知られています (Uv gotchas // Railslide // Code, experiments, and thoughts)（カレントディレクトリに.venvがないために uv が環境を見つけられない）。初心者のうちは特別な理由がない限りデフォルトの.venvを使うのがおすすめです。

まとめ

今回は、Python 初心者の方に向けてパッケージ管理ツール「uv」の概要と使い方、メリット・注意点を解説しました。最後に内容を簡単に振り返ってみましょう。

• uv とは: Rust 製の高速 Python パッケージマネージャーで、pip や venv 等を統合したオールインワンツール。ライブラリのインストールや依存関係解決が非常に速く、環境構築のストレスを大幅に軽減してくれる。
• 高速化の仕組み: 並列ダウンロード、キャッシュの活用、必要部分のみの取得などにより、pip のボトルネックを解消している。その結果、場合によっては pip の 10 倍以上の速度で処理が完了する。
• 仮想環境と依存管理: uv は仮想環境を自動で作成・管理し、pyproject.toml で依存を宣言、uv.lock で確定したバージョンを保存する。これにより開発環境の再現性が担保され、チーム開発でも安心。
• 基本コマンド: uv initでプロジェクト開始、uv add/uv removeでパッケージ追加削除、uv syncで環境同期、uv runで環境内実行など、直感的なコマンドが用意されている。
• pip との違い: 操作感は似ているが、処理速度や依存解決アルゴリズムが洗練されている点で優れる。pip+α のツールをまとめて置き換え可能で、初心者にも扱いやすい設計。
• 注意点: uv 使用時は pip コマンドを直接使わないようにし、常に uv 経由で操作する（そうしないと環境が不整合になる恐れ）。また他の環境管理ツールとの二重管理にならないように気をつける。

最初は新しいツールに戸惑うかもしれませんが、実際に使ってみると「とにかく速くて快適」というのが率直な感想になるでしょう。Python 初心者の方でも、uv を使えば仮想環境の作成から依存関係の管理、パッケージの追加までスムーズに行えます。何より、環境構築に余計な時間を取られずコーディングに集中できるのは大きなメリットです。

ぜひ一度、あなたの Python プロジェクトで uv を試してみてください。その高速さと便利さに驚くはずです。快適な Python ライフを応援しています！

詳細を確認する