uv インストールガイド：macOS、Linux、Windows、pipx、Homebrew、WinGet の選び方

Thu, 07 May 2026 23:23:58 +0800

uv は Astral が提供する Python ツールチェーンマネージャーです。Python バージョン、仮想環境、依存関係、スクリプト、プロジェクト、ツールを管理できます。インストール方法は多く、公式ドキュメントではスタンドアロンインストーラーのほか、PyPI、Homebrew、WinGet、Scoop、Docker、GitHub Releases、Cargo が案内されています。

すばやく入れたいだけなら、まず公式のスタンドアロンインストーラーを使うのがおすすめです。システムのパッケージマネージャーでバージョンを管理したいなら Homebrew、WinGet、Scoop を選びます。Python ツールを隔離環境に入れる運用に慣れているなら pipx が向いています。

すばやく選ぶ

シーン	推奨方法	コマンド
macOS / Linux で素早くインストール	公式スタンドアロンインストーラー	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
macOS / Linux に curl がない	公式スクリプト + wget	`wget -qO- https://astral.sh/uv/install.sh \| sh`
Windows で素早くインストール	PowerShell インストーラー	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`
Python ツールを隔離して入れる	pipx	`pipx install uv`
一時的または従来型の Python インストール	pip	`pip install uv`
macOS のパッケージ管理	Homebrew	`brew install uv`
macOS の MacPorts ユーザー	MacPorts	`sudo port install uv`
Windows のパッケージ管理	WinGet	`winget install --id=astral-sh.uv -e`
Windows の Scoop ユーザー	Scoop	`scoop install main/uv`
Rust ユーザー	Cargo	`cargo install --locked uv`

汎用的におすすめしやすい選択肢は次の通りです。

macOS / Linux：公式スタンドアロンインストーラー；
Windows：公式 PowerShell インストーラー、または WinGet；
pipx で Python CLI ツールを管理している場合：pipx install uv。

macOS と Linux：公式インストーラー

公式でもっとも直接的な方法は、curl でスクリプトを取得して sh に渡す方法です。

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

システムに curl がない場合は wget を使えます。

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

特定バージョンをインストールしたい場合は、URL にバージョン番号を含めます。たとえば公式例の 0.11.11 は次のようになります。

`1`	`curl -LsSf https://astral.sh/uv/0.11.11/install.sh \| sh`

この方法は、ほとんどの個人開発環境に向いています。シンプルでクロスプラットフォームであり、uv 公式の更新機構とも相性が良いからです。

インストーラーは uv、uvx などのバイナリをユーザーディレクトリ配下に配置し、コマンドをターミナルから直接使えるように shell profile を変更する場合があります。PATH を変更されたくない場合は、公式 installer オプションを確認し、たとえば UV_NO_MODIFY_PATH=1 を設定します。

Windows：PowerShell インストーラー

Windows の公式インストール方法は、PowerShell でインストーラースクリプトを実行する方法です。

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

特定バージョンをインストールする場合も、URL にバージョン番号を含めます。

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

ここでの ExecutionPolicy ByPass は、インターネットから取得したインストーラースクリプトを実行できるようにするための指定です。安全のため、実行前にスクリプト内容を確認することもできます。

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

Windows のパッケージマネージャーに慣れているなら、WinGet や Scoop を優先してもよいでしょう。

pipx でインストールする

公式ドキュメントでは、uv が PyPI に公開されていることも説明されています。PyPI からインストールする場合は、pipx などで隔離環境に入れることが推奨されます。

`1`	`pipx install uv`

この方法は、pipx を Python CLI ツールマネージャーとして使っている人に向いています。uv を現在のプロジェクト環境と混ぜずに済みます。

pipx がない場合は、pip を直接使うこともできます。

`1`	`pip install uv`

ただし、uv は多くのプラットフォーム向けに事前ビルド済み wheel を提供していますが、対象 platform の wheel がない場合はソースからビルドされます。その場合は Rust ツールチェーンが必要です。

私のおすすめは、個人マシンでは pip install uv より pipx install uv のほうがきれい、というものです。プロジェクト環境の中では、uv をプロジェクト依存関係として入れないほうがよいでしょう。

Homebrew、MacPorts、WinGet、Scoop

システムのパッケージマネージャーを好む場合、uv は一般的な配布経路にも対応しています。

macOS では Homebrew を使えます。

`1`	`brew install uv`

MacPorts ユーザーは次のコマンドです。

`1`	`sudo port install uv`

Windows では WinGet を使えます。

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

Scoop ユーザーは次の通りです。

`1`	`scoop install main/uv`

これらの方法の利点は、システムのパッケージマネージャーに一元管理できることです。欠点は、更新タイミングが uv 公式インストーラーではなく、各パッケージソースに依存することです。

Docker、GitHub Releases、Cargo

uv は GitHub Container Registry で Docker イメージも提供しています。

`1`	`ghcr.io/astral-sh/uv`

これは CI、Dockerfile、イメージビルド、一時的な実行環境に向いています。実際に使う場合は、公式の Docker 統合ドキュメントも確認するのがおすすめです。

バイナリを手動でダウンロードしたい場合は、GitHub Releases を使えます。各 release ページには通常、対応プラットフォーム向けのバイナリが含まれ、GitHub URL を使ってスタンドアロンインストーラーを呼び出す方法も説明されています。

Rust ユーザーは crates.io からもインストールできます。

`1`	`cargo install --locked uv`

ただし、この方法はソースからビルドするため、互換性のある Rust ツールチェーンが必要です。Rust エコシステムからインストールする明確な理由がない限り、一般ユーザーが Cargo を優先する必要はありません。

uv をアップグレードする

uv を公式スタンドアロンインストーラーで入れた場合は、自己更新コマンドを使えます。

`1`	`uv self update`

公式ドキュメントでは、uv の更新時にインストーラーが再実行され、shell profile が変更される可能性があると説明されています。更新時に PATH を変更されたくない場合は、次を設定します。

`1`	`UV_NO_MODIFY_PATH=1`

別の方法でインストールした場合は、その方法に対応するパッケージマネージャーでアップグレードします。たとえば pip で入れた場合は次の通りです。

`1`	`pip install --upgrade uv`

Homebrew、WinGet、Scoop、MacPorts も、それぞれのアップグレードコマンドを使います。

shell 補完を有効にする

uv は shell 補完に対応しています。公式ドキュメントでは、まず現在の shell を確認することが推奨されています。

`1`	`echo $SHELL`

Bash：

`1`	`echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc`

Zsh：

`1`	`echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc`

fish：

`1`	`echo 'uv generate-shell-completion fish \| source' > ~/.config/fish/completions/uv.fish`

PowerShell：

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

uvx もよく使う場合は、uvx の補完を別途有効にできます。

Bash：

`1`	`echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc`

Zsh：

`1`	`echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc`

fish：

`1`	`echo 'uvx --generate-shell-completion fish \| source' > ~/.config/fish/completions/uvx.fish`

PowerShell：

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

設定後は shell を再起動するか、対応する設定ファイルを再読み込みします。

uv をアンインストールする

uv をアンインストールする場合は、まずキャッシュと uv が保存しているデータを削除できます。

1
2
3

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

その後、バイナリを削除します。

macOS / Linux：

`1`	`rm ~/.local/bin/uv ~/.local/bin/uvx`

Windows：

1
2
3

rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe

公式ドキュメントでは、0.5.0 より前の uv は ~/.cargo/bin にインストールされていた点も注意されています。古いバージョンからアップグレードした場合、古いバイナリが残っていることがあるため、手動で削除する必要があります。

インストール後に最初にすること

インストール後は、まずバージョンを確認します。

`1`	`uv --version`

その後、いくつかのよく使うタスクから始められます。

uv python install
uv venv
uv pip install requests
uvx ruff --version

新規プロジェクトなら、次も確認するとよいでしょう。

uv init：プロジェクトを初期化する；
uv add：依存関係を追加する；
uv sync：環境を同期する；
uv run：プロジェクト環境でコマンドを実行する；
uvx：Python CLI ツールを一時的に実行する。

私のおすすめ

個人の開発マシンでは、公式スタンドアロンインストーラーを優先するのがおすすめです。uv 公式ドキュメントにもっとも近く、uv self update も使えるためです。

Windows ユーザーでリモートスクリプトを実行したくない場合は、WinGet や Scoop を使えます。macOS ユーザーでツールをすべて Homebrew に任せたい場合は、brew install uv で問題ありません。

すでに pipx で Python CLI ツールを管理している人は、pipx install uv を使うとよいでしょう。ただし、具体的なプロジェクトの仮想環境内で pip install uv するのはおすすめしません。ツールチェーンとプロジェクト依存関係が混ざりやすくなるからです。

CI やコンテナビルドでは、Docker と GitHub Releases を優先的に確認し、イメージビルドの流れに合わせてバージョンを固定します。

Astral on KnightLiブログ