Python の uv とは？使い方と pip・venv との違い【uv 0.12 対応】

uv は、Ruff を作った会社 Astral が支えている、Python のパッケージ管理とプロジェクト管理の道具です。公式は「Rust で書かれた、とても速い」道具と紹介し、pip・pyenv・poetry・virtualenv などでやっていたことを1つで置き換えると説明しています。

この記事は、pip と venv という名前は聞いたことがある、Python を始めたばかりの人向けです。uv でできること、Mac と Windows での入れ方、プロジェクトの作り方、pip・venv との違いを、2026年10月時点の公式の資料をもとにまとめました。

この記事で確かめた版（2026年10月時点）

• 出力例: uv 0.12.10（2026年9月4日の版）、macOS（Apple Silicon）。出力の中の /path/to/ は、作業フォルダの場所を置き換えたものです
• 最新版: uv 0.12.22（PyPI に載ったのは2026年10月2日）。公式の文書はこの版に合わせて書かれています
• Windows の手順は、公式の文書のとおりに書いています。出力例はすべて macOS のものです

uv とは？何をまとめて置き換える道具か

最初に言葉を2つだけ説明します。パッケージは、requests のように、あとから足して使う Python の部品です。プロジェクトは、uv では、使うパッケージ（依存といいます）を pyproject.toml というファイルに書いて管理する Python のプロジェクトのことです。Python という言語そのものの使われ方や代表的なフレームワークは、需要の高い人気プログラミング言語＆フレームワーク【将来性】で紹介しています。

uv でできること

公式の紹介ページにある特長のうち、この記事に関係するものは次のとおりです。

• pip と同じ形で使えるコマンド（uv pip）がある
• プロジェクトを管理でき、どの OS でも使えるロックファイル（universal lockfile。入れるパッケージの版を記録するファイル）を作る
• Python 本体の、いろいろな版を入れて管理できる
• Python のパッケージとして配られているツールを、動かしたり入れたりできる
• Rust も Python も用意しなくても入れられる
• macOS・Linux・Windows で使える

機能は「Python の版」「スクリプト」「プロジェクト」「ツール」「pip 形式のコマンド」「uv 自身の管理」に分かれていて、単独でも、組み合わせても使えます。この記事では、このうち Python の版・プロジェクト・pip 形式のコマンドを中心に説明します。

速さについて、公式は「とても速い（extremely fast）」と説明しています。この記事では速さを測っていないので、速さの数字は載せません。

uv そのものは Python に頼らずに動きます（ただし、パッケージを入れる先の Python の環境は探します）。Python を先に入れておかなくても、足りない版は必要なときに uv が入れます。

uv の基本情報と版の付け方

項目	内容
支えている会社	Astral（Ruff を作った会社）
書かれている言語	Rust
使える OS	macOS・Linux・Windows
ライセンス	MIT または Apache-2.0（PyPI の記載）
最新版	0.12.22（PyPI に載ったのは2026年10月2日。2026年10月時点）

uv の版は、それまでの使い方を壊すような変更（breaking changes）のときにマイナー版（0.12 → 0.13 のように、真ん中の数字）が上がり、バグの修正や、使い方を壊さない改善のときにパッチ版（0.12.22 のように、最後の数字）が上がる決まりで付けられています。公式は、uv を「本番で広く使われている、安定したソフトウェア」と書いています。

pip・venv・pyenv・poetry は uv の何に当たる？（対応表）

uv の公式は、pip・pip-tools・pipx・poetry・pyenv・twine・virtualenv など（「and more」と書かれています）を、1つで置き換える道具だと書いています。venv については、機能の説明のページに「venv と virtualenv を置き換える」と書かれています。まず、道具ごとの公式の言い方を表にします。

これまでの道具	何をする道具か	uv の公式の言い方
pip	パッケージを入れる	置き換える（pip と同じ形のコマンド uv pip）
venv	仮想環境を作る	置き換える（venv と virtualenv）
pyenv	複数の Python の版を切り替える	置き換える
poetry	プロジェクトと依存を管理する	置き換える（紹介ページの一覧）。プロジェクトの管理は「rye や poetry に似ている」とも書かれている

次に、これまでのコマンドと uv のコマンドの対応です。「これまで」の列は、pip と venv は PyPA（Python のパッケージの公式の作業部会）の手引き、pyenv は pyenv の README、poetry は poetry の公式の文書にあるコマンドです。表は Mac の書き方で、Windows では PyPA の手引きが py -m pip install requests・py -m venv .venv のように、python3 の代わりに py を使う形で書いています。

やりたいこと	これまで（Mac の書き方）	uv
パッケージを入れる	python3 -m pip install requests	uv pip install requests（pip 形式）／uv add requests（プロジェクト）
requirements.txt から入れる	python3 -m pip install -r requirements.txt	uv pip install -r requirements.txt／uv add -r requirements.txt
入っているものを書き出す	python3 -m pip freeze	uv pip freeze
ロックファイル（uv.lock）を requirements.txt の形で書き出す	―	uv export --format requirements.txt（プロジェクト）
仮想環境を作る	python3 -m venv .venv	uv venv
Python の版を入れる	pyenv install	uv python install 3.12
そのフォルダで使う版を決める	pyenv local <version>	uv python pin 3.13
利用者全体で使う版を決める	pyenv global <version>	uv python pin --global 3.13（版を書く）
プロジェクトを作る	poetry new／poetry init	uv init
依存を足す	poetry add	uv add
ロックファイルを作る	poetry lock	uv lock
環境に入れる	poetry install／poetry sync	uv sync
環境の中でコマンドを動かす	poetry run	uv run

表の補足です。

• poetry sync は、poetry install に加えて、ロックファイルに無いパッケージを消します。uv sync も、既定でロックファイルに無いパッケージを消します
• pip-tools を置き換えるのは uv pip compile と uv pip sync、pipx に近い機能は uvx（uv tool run の別名）です
• uv は、pyenv で入れた Python を「システムの Python」として扱います。uv で入れた Python は「managed（uv が管理する）Python」と呼ばれます
• uv が入れる Python はビルド済みのものです。uv の文書は、pyenv のようにソースからビルドする方法には、前もって入れておくシステム側の部品が要り、速いビルドを作るのはとても時間がかかる、と説明しています
• pyenv は Windows を公式には支えておらず、WSL（Windows の中で Linux を動かす仕組み）の外では動きません。uv は Windows でも使えます

pip 形式のコマンドは、pip や venv とまったく同じ動きではありません。 公式は、pip 形式のコマンド（uv venv・uv pip など）について、元の道具のインターフェースと動きを完全に実装したものではなく、よくある使い方から外れるほど違いに出会いやすい、と書いています。uv pip は pip を中で呼び出しているわけではなく（公式は「uv does not rely on or invoke pip」と書いています）、pip と同じ形にそろえた uv のコマンドです。

uv のインストール方法（Mac・Windows）

uv は、Rust も Python も用意しなくても入れられます。公式の手順は、uv の公式のインストールのページにあります。

Mac（と Linux）は公式のインストーラーで入れる

公式が最初に挙げているのは、curl でスクリプトをダウンロードして、sh で流す方法です。

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

curl が無い環境では、wget でも入れられます。

wget -qO- https://astral.sh/uv/install.sh | sh

ネットから取ったスクリプトをそのまま流すのが不安なときは、流す前に中身を見られます（less は、中身を画面ごとに送りながら読むコマンドです）。

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

版を指定して入れるときは、URL に版を入れます。公式の文書にある例は次のとおりです（0.12.22 は、2026年10月時点の最新版です）。

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

Homebrew（Mac で道具を入れるための道具）や MacPorts でも入れられます。

# Homebrew
brew install uv

# MacPorts
sudo port install uv

PyPI（Python のパッケージの置き場）から入れる方法もあります。公式は、その場合は pipx などで、ほかから切り離した環境に入れるのを勧めています（pip install uv でも入ります）。

Windows は公式の手順で入れる

Windows では、公式の手順で入れます。PowerShell で、次のコマンドを流します（公式のインストールのページと同じ手順です）。

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

-ExecutionPolicy ByPass は、実行ポリシー（PowerShell でスクリプトを動かせるかどうかの設定）を変えて流すための指定です。公式は、実行ポリシーを変えると、ネットのスクリプトを流せるようになる、と説明しています。

Mac と同じく、流す前にスクリプトの中身を見ることもできます。

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

WinGet や Scoop でも入れられます。

winget install --id=astral-sh.uv  -e
scoop install main/uv

入ったか確かめる

入ったかどうかは、uv --version で確かめます。

uv 0.12.10（macOS）の出力:

$ uv --version
uv 0.12.10 (3c979abda 2026-09-04 aarch64-apple-darwin)

uv 0.12.10 では、uv とだけ打つと error: 'uv' requires a subcommand but one was not provided というエラーになります。これは、uv は見つかったが、サブコマンド（run や init のような、uv に頼む内容）が足りない、という意味のエラーです。コマンドの一覧を見たいときは uv --help を使います。

PATH が通らないとき

uv と打っても見つからないときは、PATH を確かめます。PATH は、コマンドの名前からプログラムを探しにいく場所の一覧です。

インストーラーは、uv を「利用者の実行ファイルの置き場」に入れます。XDG という設定の環境変数を使っていなければ、Mac は $HOME/.local/bin、Windows は %USERPROFILE%\.local\bin です。

• インストーラーは、uv に PATH が通るように、シェル（ターミナルの中でコマンドを受け付けるプログラム）の設定ファイルを書き換えることがあります。止めたいときは、環境変数 UV_NO_MODIFY_PATH を使います
• Mac のインストーラーは、設定ファイルを書き換えたとき、シェルを開き直すか、source $HOME/.local/bin/env を流すよう案内します
• Windows のインストーラーも、PATH を足したときは、シェルを開き直すか、cmd なら set Path=...、PowerShell なら $env:Path = ... の形のコマンドを流すよう案内します

アップデートとアンインストール

インストーラーで入れた uv は、uv self update で自分自身を更新できます。ほかの入れ方では自己更新は使えないので、その入れ方のアップデートの方法（例: pip install --upgrade uv）を使います。uv self update はインストーラーを流し直すので、シェルの設定ファイルを書き換えることがあります。止めたいときは UV_NO_MODIFY_PATH=1 を付けます。

アンインストールは、公式の手順では2段階です。Mac の手順は次のとおりです。

# 1. 必要なら、uv が保存したデータ（キャッシュ・入れた Python・入れたツール）を消す
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

# 2. uv 本体を消す
rm ~/.local/bin/uv ~/.local/bin/uvx

rm -r は、指したフォルダを中身ごと消します。消したものは元に戻せないので、何を消すコマンドかを確かめてから流してください。Windows では、uv.exe・uvx.exe・uvw.exe を消します（手順は公式のページにあります）。

uv でプロジェクトを作って動かすには？（init・add・run・lock・sync）

uv の「プロジェクト」は、使うパッケージを pyproject.toml に書いて管理する Python のプロジェクトです。コマンドは、作る uv init、依存を足す uv add、環境を合わせる uv sync、ロックファイルを作る uv lock、環境の中で動かす uv run の5つが中心です。

まず知っておきたい：uv 0.12 から uv init の形が変わった

uv 0.12 より前は、アプリ用のプロジェクトにビルドの設定（build system）を書きませんでした。0.12 からは、アプリ用のプロジェクトでも、ビルドの設定を書き、ソースを src/<プロジェクト名>/ というフォルダに置くのが既定です（公式の文書より）。

古い記事にある、main.py だけが置かれる平たい形で作るときは、--no-package を付けます（あとの「main.py の形で作る」で説明します）。ビルドの設定は、ここでは「uv init が書いてくれる設定」とだけ押さえておきます。

プロジェクトを作る（uv init）

フォルダごと作るときは、プロジェクト名を付けます。

uv init hello-uv

すでにあるフォルダの中で作るときは、そのフォルダに入って uv init だけを流します。既定ではアプリ用（Web サーバー・スクリプト・コマンドラインの道具向け）で、ライブラリ用なら --lib を付けます。

uv init hello-uv のあとの hello-uv フォルダの中身です（uv 0.12.10・macOS。Git の管理用の .git/ は省いています）。

.
./.gitignore
./.python-version
./README.md
./pyproject.toml
./src
./src/hello_uv
./src/hello_uv/__init__.py

ファイル・フォルダ	役目
pyproject.toml	依存や、プロジェクトの説明（description や license など）を書くファイルです。手で直してもよいし、uv add・uv remove で直してもよいです
.python-version	そのプロジェクトの既定の Python の版です。仮想環境を作るときに、どの版を使うかを uv に伝えます
src/hello_uv/__init__.py	プログラムを置く場所です。プロジェクト名 hello-uv に対して、src/hello_uv/ ができます
.gitignore	Git に入れないものを書くファイルです。uv init が作ります。詳しくは【完全入門】Git .gitkeep と .gitignore の違いと使い分けの話で説明しています
README.md	説明を書くファイルです。作った直後は空です
.git/	Git のリポジトリです。uv init は既定で作ります。作りたくないときは --vcs none を付けます

.python-version には、uv が見つけた Python の版（マイナー版まで）が書かれます。出力例では 3.14 で、pyproject.toml の requires-python（使える Python の版の条件）も、見つかった Python から >=3.14 になっています。

pyproject.toml の中身です（uv 0.12.10）。

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

[project.scripts]
hello-uv = "hello_uv:main"

[build-system]
requires = ["uv_build>=0.12.10,<0.13.0"]
build-backend = "uv_build"

[build-system] の行の数字は、uv の版で変わります（公式の文書の例は、0.12.22 に合わせて uv_build>=0.12.22,<0.13 と書かれています）。また、uv は作者（authors）の欄を、既定で Git の設定などから埋めようとします。上の例は Git の利用者の設定が読まれない状態で出したものなので、authors の行がありません。

動かす（uv run）

uv run で、プロジェクトのコマンドを動かします。pyproject.toml の [project.scripts] には hello-uv = "hello_uv:main" という行があり、src/hello_uv/__init__.py には main という関数があります。

def main() -> None:
    print("Hello from hello-uv!")

uv 0.12.10（macOS）の出力:

$ uv run hello-uv
Using CPython 3.14.7
Creating virtual environment at: .venv
   Building hello-uv @ file:///path/to/hello-uv
      Built hello-uv @ file:///path/to/hello-uv
Installed 1 package in 3ms
Hello from hello-uv!

.venv（仮想環境）と uv.lock（ロックファイル）は、最初に uv run・uv sync・uv lock のどれかを流したときにできます。上の出力にも Creating virtual environment at: .venv と出ています。

ファイル・フォルダ	役目
.venv	プロジェクトの仮想環境です。仮想環境は、ほかから切り離された Python の環境で、依存はここに入ります。エディタが見つけやすいように、既定ではプロジェクトの中に置かれます
uv.lock	ロックファイルです。入れるパッケージの版を正確に記録します。uv が管理するファイルなので、手で直しません。形式は uv 専用で、ほかの道具では読めません

uv.lock は Git に入れます。マシンが変わっても、同じ版で入れ直せるようにするためです。.venv は Git に入れません。uv は .venv の中に .gitignore を置いて Git から外していて、プロジェクトの .gitignore にも .venv が書かれています。エディタなど、プログラミングを始めるときの道具そのものは、【プログラミング完全入門】必ず使う最低限必要なツール紹介！で紹介しています。

パッケージを足す・外す（uv add・uv remove）

例として、パッケージ requests を足します。uv add は、pyproject.toml に依存を足し、ロックファイルと環境も一緒に更新します。

uv add requests

uv 0.12.10（macOS）の出力:

Resolved 6 packages in 136ms
   Building hello-uv @ file:///path/to/hello-uv
      Built hello-uv @ file:///path/to/hello-uv
Prepared 6 packages in 86ms
Uninstalled 1 package in 1ms
Installed 6 packages in 5ms
 + certifi==2026.7.22
 + charset-normalizer==3.5.2
 ~ hello-uv==0.1.0 (from file:///path/to/hello-uv)
 + idna==3.20
 + requests==2.34.2
 + urllib3==2.8.0

+ が付いた行が、新しく入ったパッケージです。requests と、requests が使う4つのパッケージ（certifi・charset-normalizer・idna・urllib3）が入っています。pyproject.toml の dependencies には、次のように書かれます。

dependencies = [
    "requests>=2.34.2",
]

版を決めずに足したときは、そのとき合う最新版を下限にした条件（ここでは >=2.34.2）が書かれます。版を決めて足すこと（uv add 'requests==2.31.0'）や、Git から足すこと（uv add git+https://github.com/psf/requests）もできます。足したパッケージは、uv run で使えます。次は uv 0.12.10（macOS）の出力です。

$ uv run python -c 'import requests; print(requests.__version__)'
2.34.2

外すときは uv remove を使います。requests と一緒に入った4つのパッケージも外れます。出力の一部です（uv 0.12.10・macOS。プロジェクト自身の ~ hello-uv の行は省いています）。

$ uv remove requests
Uninstalled 6 packages in 19ms
 - certifi==2026.7.22
 - charset-normalizer==3.5.2
 - idna==3.20
 - requests==2.34.2
 - urllib3==2.8.0

ロックと同期（uv lock・uv sync）

2つの言葉を押さえます。ロックは、依存を解決して、ロックファイルに書くことです。同期（sync）は、ロックファイルから、プロジェクトの環境にパッケージを入れることです。ふだんは自動で、uv run を流すと、動かす前にロックと同期が行われます。

uv run は、動かす前に毎回、ロックファイルが pyproject.toml と合っているか、環境がロックファイルと合っているかを確かめます。手で合わせる必要はありません。公式は、uv run が、ロックした版がそろった環境でコマンドを動かすことを保証する、と書いています。

コマンド	役目
uv lock	依存を解決して、ロックファイルを作る（更新する）
uv lock --check	ロックファイルが最新かどうかを確かめる
uv sync	ロックファイルに合わせて環境を整える。.venv が無ければ作る。ロックファイルに無い余分なパッケージは、既定で消す
uv run	プロジェクトの環境の中でコマンドを動かす。ロックファイルに無い余分なパッケージは、既定では消さない
uv tree	依存の木（どのパッケージが、どのパッケージを使っているか）を見る

requests を足した状態で流した出力です（uv 0.12.10・macOS）。

$ uv lock
Resolved 6 packages in 2ms

$ uv lock --check
Resolved 6 packages in 2ms

$ uv sync
Resolved 6 packages in 3ms
Checked 6 packages in 0.18ms

$ uv tree
Resolved 6 packages in 2ms
hello-uv v0.1.0
└── requests v2.34.2
    ├── certifi v2026.7.22
    ├── charset-normalizer v3.5.2
    ├── idna v3.20
    └── urllib3 v2.8.0

• ロックファイルが古ければ、直さずにエラーにしたいときは --locked、古いかどうかを確かめずにロックファイルを使いたいときは --frozen を使います
• 新しい版が出ても、uv.lock は「古い」扱いにはなりません。上げたいときは、明示して上げます。1つだけなら uv lock --upgrade-package <パッケージ名>（ほかはロックのまま）、全部なら uv lock --upgrade です
• uv sync を手で流すのは、エディタに正しい版の依存を見せたいときに特に役立ちます

uv run を付けずに動かすには

プロジェクトの環境は、今のシェルから切り離されています。そのため、プロジェクトのパッケージを使うコマンド（公式の例は python -c "import example"）を、そのまま流すと失敗します。プロジェクトを使うコマンドは、uv run を付けて動かします。uv run file.py は uv run python file.py と同じです。

uv run を使わないときは、uv sync で環境を整えてから、仮想環境を有効にして、コマンドを動かします。この場合は、仮想環境を有効にしておく必要があります。

# Mac
uv sync
source .venv/bin/activate

# Windows（PowerShell）
uv sync
.venv\Scripts\activate

main.py の形で作る（--no-package）

古い記事にある、main.py だけが置かれる形で作るときは、--no-package を付けます。ビルドの設定は使われません。

uv init --no-package hello-flat

uv 0.12.10（macOS）での、hello-flat フォルダの中身と main.py です（.git/ は省いています）。

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

def main():
    print("Hello from hello-flat!")


if __name__ == "__main__":
    main()

uv run main.py で動かせて、Hello from hello-flat! と表示されます。

一度だけ使うパッケージは uvx か uv run --with で

プロジェクトの環境に、uv pip install で手を入れるのは、公式は勧めていません。プロジェクトの依存は uv add で足します。一度だけ使うものは、uvx か uv run --with を使います。

• uvx は、ツールを入れずに動かします。ツールは、一時的な、ほかから切り離された環境に入ります
• uv run --with は、その1回の実行だけ、追加の依存を使います

requests を外したプロジェクトで、次のコマンドを流すと、requests が使えます（uv 0.12.10・macOS）。

$ uv run --with requests python -c 'import requests; print(requests.__version__)'
Installed 5 packages in 3ms
2.34.2

Python で Web API を作る流れは、FastAPI を使った【Python入門】Fast APIの実装手順とフレームワーク技術選定の記事で解説しています。

uv venv と Python 本体の管理（uv python install）

ここでは、pip 形式の uv venv と、Python 本体を入れる uv python install を説明します。

仮想環境とは

仮想環境は、Python 本体の環境から、パッケージを切り離す軽い仕組みです（uv の文書の説明）。Python 本体の環境を直接いじらないのが、よいやり方とされています。

uv は、既定で仮想環境を使います。pip は、仮想環境を有効にしていないと全体の環境にパッケージを入れ、有効にしていない仮想環境は探しません。ここが pip との違いの1つです。

uv venv で仮想環境を作る

uv venv は、今のフォルダに .venv という仮想環境を作ります。

uv 0.12.10（macOS）の出力:

$ uv venv
Using CPython 3.14.7
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

名前（場所）を変えるなら、uv venv my-name のように指定します。Python の版を指定するなら、uv venv --python 3.11 のようにします。その Python がパソコンに無いときは、uv がダウンロードします。

uv 0.12.10（macOS）の出力です。Python 3.13 が入っていない状態で uv venv --python 3.13 py313 を流すと、uv が 3.13.15 をダウンロードして、py313 というフォルダに仮想環境を作ります。

$ uv venv --python 3.13 py313
Downloading cpython-3.13.15-macos-aarch64-none (download) (24.0MiB)
 Downloaded cpython-3.13.15-macos-aarch64-none (download)
Extracting cpython-3.13.15-macos-aarch64-none (extract) (24.0MiB)
 Extracted cpython-3.13.15-macos-aarch64-none (extract)
Using CPython 3.13.15
Creating virtual environment at: py313
Activate with: source py313/bin/activate

uv のコマンドで使うなら、仮想環境を有効（activate）にしなくても使えます。uv が、今のフォルダか親のフォルダにある .venv を見つけるからです。有効にしたいときは、Mac は source .venv/bin/activate、Windows は .venv\Scripts\activate を流し、抜けるときは deactivate を流します。

uv venv で作った環境へは、uv pip install でパッケージを入れます。有効にした仮想環境があればそこに、無ければ今のフォルダか親のフォルダの .venv に（有効にしていなくても）入ります。

uv 0.12.10（macOS）の出力:

$ uv pip install requests
Resolved 5 packages in 51ms
Installed 5 packages in 3ms
 + certifi==2026.7.22
 + charset-normalizer==3.5.2
 + idna==3.20
 + requests==2.34.2
 + urllib3==2.8.0

$ uv pip list
Package            Version
------------------ ---------
certifi            2026.7.22
charset-normalizer 3.5.2
idna               3.20
requests           2.34.2
urllib3            2.8.0

uv venv で作った環境には pip が入らない（--seed）

uv venv で作った環境には、pip が入りません。 python -m pip を流すと、次のようにエラーになります。

uv 0.12.10（macOS）の出力です（先頭の場所は、作業フォルダの場所を置き換えています）。

$ .venv/bin/python -m pip --version
/path/to/pip-style/.venv/bin/python: No module named pip

pip も入れたいときは、--seed を付けます。--seed を付けると、seed packages（pip・setuptools・wheel のうちの1つ以上）が仮想環境に入ります。ただし、Python 3.12 以降の環境には、setuptools と wheel は入りません。

uv 0.12.10（macOS）の出力です。--clear は、すでにある .venv を作り直す指定です（あとの「つまずきやすい所」で説明します）。

$ uv venv --seed --clear
Using CPython 3.14.7
Creating virtual environment with seed packages at: .venv
 + pip==26.2.1
Activate with: source .venv/bin/activate

パッケージを入れるだけなら、pip が無くても、上のとおり uv pip install で入れられます。Python 標準の venv は、これと違って、既定で pip を入れます（3.4 から。入れないなら --without-pip）。

uv python install で Python 本体を入れる

uv は、Python 本体も入れられます。Python を先に入れておかなくても、足りない版は必要なときに uv が入れます。uv が入れる Python は、Astral の python-build-standalone プロジェクトが配っているものです。

やりたいこと	コマンド
版を書かずに入れる（.python-version などが無く、まだ何も入れていなければ最新の正式版）	uv python install
版を指定して入れる	uv python install 3.12
複数の版を入れる	uv python install 3.11 3.12
入っている版と入れられる版の一覧を見る	uv python list
入っている版だけの一覧を見る	uv python list --only-installed
使われる Python の場所を見る	uv python find
使う版を固定する	uv python pin 3.13
入れた Python を消す	uv python uninstall 3.12（版を書く）

uv 0.12.10（macOS）の出力:

$ uv python install 3.14
Downloading cpython-3.14.7-macos-aarch64-none (download) (25.3MiB)
 Downloaded cpython-3.14.7-macos-aarch64-none (download)
Extracting cpython-3.14.7-macos-aarch64-none (extract) (25.3MiB)
 Extracted cpython-3.14.7-macos-aarch64-none (extract)
Installed Python 3.14.7 in 2.58s
 + cpython-3.14.7-macos-aarch64-none (python3.14)

このあとに、PATH についての警告が出ることがあります（「つまずきやすい所」で説明します）。

uv python list の出力の一部です（uv 0.12.10・macOS。上の uv python install 3.14 を流す前のもの）。<download available> と出ている行は、入れられる版です。パスが出ている行は、すでに入っている Python です。

$ uv python list
cpython-3.14.7-macos-aarch64-none                    <download available>
cpython-3.13.15-macos-aarch64-none                   <download available>
cpython-3.12.14-macos-aarch64-none                   <download available>
cpython-3.11.16-macos-aarch64-none                   <download available>
cpython-3.10.21-macos-aarch64-none                   <download available>
cpython-3.9.25-macos-aarch64-none                    <download available>
cpython-3.9.6-macos-aarch64-none                     /usr/bin/python3

入れられる Python の版は、uv の版ごとに決まっています。新しい Python を入れるには、uv を上げる必要があることもあります。uv 0.12.10 の一覧にある最新の正式版は、3.14.7 です。

公式の例（Unix。Mac もここに入ります）では、入れた Python は python3.12 のように版つきの名前で ~/.local/bin に置かれ、Python 本体は ~/.local/share/uv/python に置かれます。python や python3 の名前でも置きたいときは、実験的な --default を付けます。Windows では置き場が違います。どこにあるかは uv python dir で確かめられます。

Python は、必要なときに自動でダウンロードされるのが既定です。止めたいときは、設定 python-downloads を manual にします。そうすると、uv python install のときだけダウンロードされます。すでにパソコンに入っている Python があれば、uv はそれも使います。新しくダウンロードするより、入っている Python が先に選ばれます。

使う版を決めたいときは、uv python pin を使います。.python-version ファイルが書かれ、ほかの uv のコマンドがそれを見て版を決めます。uv は .python-version を、今のフォルダから親のフォルダへ順に探します。利用者全体の既定にするなら、uv python pin --global 3.13 のように版を付けます。CLI のリファレンスによると、版を書かないと、いま決まっている版を表示するだけです。

Windows では、uv で入れた Python は Windows のレジストリ（設定を保存する場所）に登録されます。py ランチャーから選べて、公式の例は py -V:Astral/CPython3.13.1 です。パッチ版（3.13.1 のような最後の数字）を上げる uv python upgrade は、2026年10月時点ではプレビューで、動きが変わることがあります。

venv と uv、どっちを使う？違いと公式の位置づけ

「venv と uv のどちらを使うべきか」を決める文は、この記事で確かめた公式の資料（PyPA の Tool recommendations、Python の venv の文書、uv の文書）には見つかりませんでした（2026年10月時点）。ここでは、2つの違いと、それぞれの公式の位置づけを並べます。選ぶときの材料にしてください。

標準の venv と uv venv の違い

項目	Python 標準の venv	uv venv
入手	Python の標準ライブラリ（3.3 で追加）。別に入れなくても使える	uv を別にインストールする
作り方	python3 -m venv .venv（Mac）／py -m venv .venv（Windows）	uv venv
場所の指定	必須。付けないとエラーになる	省略すると、今のフォルダの .venv に作る
pip	既定で入る（3.4 から）。入れないなら --without-pip	入らない。入れるなら --seed
Python の版	すでにある Python の上に作る。作るのに使った Python で決まる	--python 3.11 のように指定できる。無ければ uv がダウンロードする
有効にすること	有効にすると、その環境の python と pip が PATH に入る。有効にしなくても、仮想環境の Python をフルパスで呼べば使える	uv のコマンドでは不要。今のフォルダか親のフォルダの .venv を uv が見つける

仮想環境のフォルダを Git に入れない、という点は共通です。PyPA の手引きは、仮想環境のフォルダを .gitignore などでバージョン管理から外しておくべきだと書いています。Python の venv は、3.13 から Git 用の .gitignore も作ります。uv の文書も、.venv を Git に入れるのは勧めないと書いていて、uv のプロジェクトでは .venv の中に .gitignore が置かれます。

Python と PyPA の側の位置づけ

• venv は Python の標準ライブラリで、軽い「仮想環境」を作ります。PyPA の手引きは、他人が作ったパッケージを使うときは、仮想環境を使うことを推奨しています。uv も既定で仮想環境を使うので、仮想環境を使う点は同じです
• PyPA の「Tool recommendations」（道具のおすすめ）は、仮想環境を手で作って使う標準の道具として virtualenv と venv を、PyPI からパッケージを入れる標準の道具として pip を挙げています。同じページは、多くの作業については、あえて一律のおすすめはしない、とも書いています。このページに uv の名前は出てきません（2026年10月時点）
• Python の文書には「仮想環境の作成には、venv の使用が今は推奨されています」という一文があります。これは Python 3.5 で、それまでの pyvenv というコマンドから venv に替わったときの説明です。uv と比べた推奨ではありません

uv の側の位置づけ

• uv の文書では、プロジェクトの主なコマンドが、仮想環境を自動で管理します。pip と違い、uv は「有効にした（active）仮想環境」を中心に考えず、プロジェクトごとに .venv という専用の仮想環境を使います
• pip 形式のコマンド（uv venv・uv pip）は、仮想環境を直接扱います。公式は、これを「古いやり方や、上位のコマンドでは足りないとき向け」と位置づけています
• 一方で、公式は uv を、venv や virtualenv を「置き換える」ものと説明しています（機能の説明のページ）

選ぶときの見方

ここまでの違いから、考えるときの見方を3つにまとめます。どちらを選ぶべきかを決めるものではありません。

• 追加のインストールが要るか: venv は Python に最初から入っています。uv は別にインストールします
• pip を使うか: venv の環境には pip が入ります。uv venv の環境には pip が入らず、パッケージは uv pip install で入れます（--seed で pip も入れられます）
• Python の版や依存の記録まで任せるか: venv は、作るのに使った Python で版が決まります。uv は、Python の版（uv python install・--python）と、依存の記録（pyproject.toml と uv.lock）まで、まとめて扱えます

つまずきやすい所（uv 0.12.10 のエラーと対処）

エラーや警告の文面は、すべて uv 0.12.10（macOS）のものです。版が変わると、文面や動きが変わることがあります。この記事のほかの節で説明したつまずきは、次の場所にあります。

• uv venv の環境に pip が無い: 「uv venv で作った環境には pip が入らない（--seed）」
• uv と打っても見つからない、uv とだけ打つとエラーになる: 「PATH が通らないとき」「入ったか確かめる」
• プロジェクトのパッケージが見つからない: 「uv run を付けずに動かすには」

すでに .venv がある場所で uv venv を流すと

uv 0.12.10 では、すでに .venv がある場所で uv venv を流すと、流し方によって動きが分かれます。

• ターミナルに自分で打ったとき: 置き換えるかどうかを聞かれます（y か n）。n と答えるとエラーで止まり、y と答えると作り直されます
• 入力を渡さない形（uv venv < /dev/null）で流したとき: 聞かずに、エラーで止まります

聞かれるときの文面は次のとおりです。

A virtual environment already exists at `.venv`. Do you want to replace it? [y/n]

エラーで止まったときの出力は次のとおりです。

$ uv venv < /dev/null
Using CPython 3.14.7
Creating virtual environment at: .venv
error: Failed to create virtual environment
  Caused by: A virtual environment already exists at: .venv

hint: Use the `--clear` flag or set `UV_VENV_CLEAR=1` to replace the existing virtual environment

聞かずに作り直したいときは、--clear を付けるか、環境変数 UV_VENV_CLEAR=1 を設定します。

別の仮想環境を有効にしたまま uv を使うと警告が出る

別の仮想環境を有効にしたまま（環境変数 VIRTUAL_ENV が別の場所を指したまま）プロジェクトで uv を使うと、警告が出て、プロジェクトの .venv が使われます。

$ uv run python -c 'import sys; print(sys.prefix)'
warning: `VIRTUAL_ENV=/path/to/pip-style/.venv` does not match the project environment path `.venv` and will be ignored; use `--active` to target the active environment instead
/path/to/hello-uv/.venv

有効にした仮想環境のほうを使わせたいときは、--active を付けます。

uv python pin が requires-python に合わずにエラーになる

pyproject.toml の requires-python（使える Python の版の条件）に合わない版は、uv python pin で固定できません。uv は、プロジェクトのコマンドを流すとき、requires-python を守ります。

$ uv python pin 3.13
error: The requested Python version `3.13` is incompatible with the project `requires-python` value of `>=3.14`.

requires-python に合う版を選ぶか、pyproject.toml の requires-python を見直します。

uv init がエラーになる、思った場所に作られない

すでに pyproject.toml があるフォルダで uv init を流すと、エラーになります。

$ uv init hello-uv
error: Project is already initialized in `/path/to/hello-uv` (`pyproject.toml` file exists)

また、親のフォルダのどこかに pyproject.toml があると、新しいプロジェクトは、その親のワークスペースの一員として作られます（公式の説明です）。別のプロジェクトの中で uv init を流すときは、注意してください。

Python の置き場に PATH が通っていないと警告が出る

uv python install のあとに、次のような警告が出ることがあります。uv が入れた Python の実行ファイルの置き場に、PATH が通っていないときの警告です。

warning: `/path/to/python-bin` is not on your PATH. To use installed Python executables, run `export PATH="/path/to/python-bin:$PATH"` or `uv python update-shell`.

上の出力は、置き場を ~/.local/bin 以外の場所に設定した状態のものです。ふつうに入れた uv では、置き場は ~/.local/bin で、警告が出るかどうかは PATH しだいです。

Windows の PowerShell で Activate.ps1 が動かないとき

Python の文書には、Windows では、ユーザー向けの実行ポリシーを設定しないと、Activate.ps1（PowerShell で仮想環境を有効にするスクリプト）が使えないことがある、と書かれています。文書にある設定のコマンドは次のとおりです。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

出どころは、Python のvenv の文書です。実行ポリシーを変えるコマンドなので、意味を確かめてから流してください。uv run を使うなら、仮想環境を有効にしなくても動かせます。

よくある質問

uv pip と pip の違いは？

uv pip は、pip を中で呼び出しているわけではなく、pip と同じ形にそろえた uv のコマンドです。主な違いは次のとおりです。

• 仮想環境: pip は、仮想環境を有効にしていないと全体の環境にパッケージを入れ、有効にしていない仮想環境は探しません。uv は、既定で仮想環境を使います。有効にした仮想環境があればそこに、無ければ今のフォルダか親のフォルダの .venv に（有効にしていなくても）入れます
• 設定: uv は、pip.conf や PIP_INDEX_URL のような、pip 専用の設定ファイルや環境変数を読みません
• 動き: uv は pip の完全な写しではありません。よくある使い方から外れるほど、動きの違いに出会いやすくなります

uv pip install と uv add の違いは？

uv add は、pyproject.toml に依存を足し、ロックファイルと環境も一緒に更新します。プロジェクトの主なコマンドで、仮想環境は自動で管理されます。uv pip install は、pip 形式のコマンドで、仮想環境を直接扱います。

公式は、pip 形式のコマンドを「古いやり方や、上位のコマンドでは足りないとき向け」と位置づけています。また、プロジェクトの環境に uv pip install で手を入れるのは勧めない、プロジェクトの依存は uv add で足す、と書いています。

requirements.txt から入れるには？

pip 形式なら、uv pip install -r requirements.txt です。uv のプロジェクトに取り込むなら、uv add -r requirements.txt で、ファイルにある依存をまとめて足せます（requirements.txt から移行するときの方法として、公式が書いています）。

pip からの移行ガイドでは、uv.lock は requirements.txt の、pyproject.toml は requirements.in の代わりだと説明されています。反対に、プロジェクトから requirements.txt を書き出すときは、uv export --format requirements.txt を使います。pip で入っているものを書き出す python3 -m pip freeze に当たるのは、uv pip freeze です。

uv venv で作った仮想環境は有効（activate）にしないといけない？

uv のコマンドを使うなら、有効にしなくても使えます。uv が、今のフォルダか親のフォルダにある .venv を見つけるからです。有効にするなら、Mac は source .venv/bin/activate、Windows は .venv\Scripts\activate で、抜けるときは deactivate です。

プロジェクトで uv run を使わずにコマンドを流すときは、仮想環境を有効にしておく必要があります。Python の文書も、仮想環境の Python をフルパスで呼べば、有効にしなくてよいと書いています。

仮想環境を消す・作り直すには？

Python の文書は、仮想環境を使い捨てのものとして扱っています。消して作り直せばよく、コードは環境の中に置かず、移動やコピーもしないで、行き先で作り直す、という考え方です。いつでも作り直せるように、requirements.txt のような方法を持っておくべきだとも書かれています。

仮想環境は1つのフォルダ（慣例では、プロジェクトの中の .venv か venv）の中にあります。そのフォルダを消せば、環境は消えます。消す前に、どのフォルダを消すのかを確かめてください。uv 0.12.10 で .venv を作り直すときは、uv venv --clear を使います。

まとめ

• uv は、Python のパッケージ管理とプロジェクト管理の道具です。公式は、pip・pip-tools・pipx・poetry・pyenv・twine・virtualenv などを1つで置き換えると書いています（venv は機能の説明のページで）。ただし、pip 形式のコマンドも、pip や venv とまったく同じ動きではありません
• 入れ方は、Mac は curl のインストーラー（Homebrew でも入ります）、Windows は公式の手順（PowerShell など）です。入ったかは uv --version で確かめます
• プロジェクトは、uv init で作り、uv add で依存を足し、uv run で動かします。uv 0.12 から、src/ とビルドの設定が既定になりました。main.py の形は uv init --no-package で作ります
• uv.lock は Git に入れて、手では直しません。.venv は Git に入れません
• uv venv で作った環境には pip が入りません。入れるなら --seed を付けます。パッケージは uv pip install で入れられます
• venv と uv のどちらを使うべきかを決める文は、この記事で確かめた公式の資料には見つかりませんでした（2026年10月時点）。PyPA の道具のおすすめのページは、多くの作業で一律のおすすめをしないとしつつ、仮想環境の標準の道具に venv と virtualenv、パッケージを入れる標準の道具に pip を挙げています（uv の名前はありません）。uv は pip 形式のコマンドを、古いやり方や上位のコマンドでは足りないとき向けと位置づけています。違いと位置づけを見て選びます
• 出力例は uv 0.12.10（macOS）のものです。版が変わると、文面や動きが変わることがあります

参考資料

この記事は、次の公式の資料をもとに書きました（2026年10月時点）。

• uv の公式の文書（トップ）
• uv の公式: インストール
• uv の公式: 機能の説明（Features）
• uv の公式: プロジェクトの使い方
• uv の公式: プロジェクトの作り方（uv init）
• uv の公式: Python を入れる
• uv の公式: Python の版
• uv の公式: pip 形式の仮想環境
• uv の公式: pip からの移行
• uv の公式: pip との互換
• uv の公式: コマンドのリファレンス
• uv の公式: 版の付け方
• PyPI: uv
• Python の文書: venv
• PyPA の手引き: pip と仮想環境を使ったパッケージのインストール
• PyPA: Tool recommendations（道具のおすすめ）
• pyenv の README
• poetry の文書: コマンド

※この記事は、公式の資料をもとに AI（Claude）で下書きし、2026年10月3日時点の公式の資料と照らして確かめてから公開しています。誤りに気づいたらお問い合わせからお知らせください。