【完全版】エンジニアのための生成AI・AIエージェント活用ガイド
Ubuntu・Linux完全ガイド｜初期設定からサーバー構築まで
WSL2＋Dockerで作るWindows開発環境構築まとめ
【完全版】Git初心者向けガイド｜基本コマンドから実務トラブル解決まで
【毎朝7時更新】最新IT・テクノロジーニュース速報＆トレンドまとめ

uv python installのエラー原因と対処法｜SSL証明書・PATH問題

Pythonの超高速パッケージ・バージョン管理ツールである uv を使って、新しいPython環境を導入しようと uv python install コマンドを実行した際、「SSL証明書の検証エラー（UnknownIssuer）でダウンロードが止まる」「インストールは成功したのに python コマンドが認識されない（PATHが通らない）」といったトラブルに直面することがあります。

特にWindows環境や、社内プロキシ・セキュリティソフト（Zscaler、FortiGate、ウイルス対策ソフトのHTTPSスキャン機能など）が導入されているPCでは、uv の内部設計（OS標準の証明書ストアではなく独自の同梱証明書をデフォルトで使用する仕様）が原因で、ブラウザからは普通にインターネットへ繋がるのに uv python install だけが失敗する現象が頻発します。

この記事では、uv python install 実行時によく発生するエラーの原因を紐解き、SSL証明書エラーを1発で回避する --system-certs オプションや uv.toml の永続設定、インストール後に python コマンドへパスを通す --default と uv python update-shell の正しい使い方までを実践的な手順で解説します。

  1. この記事で行うこと
  2. 前提条件・対象読者
  3. 1. uv python install でよくあるエラーと解決コマンド早見表
  4. 2. SSL証明書エラー（UnknownIssuer）で失敗する原因と対処法
    1. なぜブラウザでは繋がるのに uv だけSSLエラーになるのか？
    2. 解決策1：–system-certs フラグを付けて実行する（一時的・即効）
    3. 解決策2：uv.toml に system-certs = true を記述して永続化する（推奨）
      1. Windows（PowerShell）での永続設定手順
      2. WSL2（Linux）/ macOS での永続設定手順
    4. 解決策3：独自のCA証明書ファイル（.pem / .crt）を直接指定する場合
  5. 3. インストールしたのに python コマンドが使えない（PATHが通らない）時の対処法
    1. 原因：デフォルトではバージョン付きコマンドしか配置されない仕様
    2. 解決手順1：–default フラグを付けて python コマンドを有効化する
    3. 解決手順2：uv python update-shell で環境変数 PATH を自動登録する
    4. 注意点：Windowsで Microsoft Store が勝手に開く場合の対策
  6. 4. プロキシ環境やGitHubダウンロード制限でタイムアウトする時の対処法
    1. 解決策1：プロキシ環境変数（HTTPS_PROXY）を設定する
    2. 解決策2：社内ミラーや代替URL（UV_PYTHON_INSTALL_MIRROR）を指定する
  7. 5. 権限エラー（os error 5 / os error 32）やファイル破損で失敗する時の対処法
    1. 原因と解決手順
  8. まとめ
  9. 次に読むおすすめ記事
  10. 参考情報

この記事で行うこと

  1. uv python install で発生する主要エラーメッセージと解決コマンドを早見表で確認する
  2. Windows環境や社内ネットワークで頻発するSSL証明書エラー（UnknownIssuer）の原因と --system-certs による解決手順を解説する
  3. インストールしたのに python コマンドが使えない（PATHが通らない）原因と、--default・uv python update-shell による解決手順を解説する
  4. プロキシ環境やGitHubダウンロード制限による接続タイムアウト時の回避策（ミラー設定・環境変数）を解説する
  5. Windowsセキュリティやファイルロックによる権限エラー（os error 5 / os error 32）の対処法を説明する

前提条件・対象読者

項目内容
対象OSWindows 11（PowerShell）、WSL2（Ubuntu）、macOS
対象ツールAstral uv（uv 0.5.x 以降〜最新バージョン対応）
最終確認日2026年10月19日
対象読者uv python install がエラーで失敗する方、またはインストール後に python コマンドが動かず困っている方

なお、uv 自体の基本的なインストール方法や、pip・Poetry からの移行手順、日常よく使うコマンド一覧については以下の記事で基礎から解説しています。

1. uv python install でよくあるエラーと解決コマンド早見表

まずは、ターミナルに表示されているエラー内容や症状から、最短で解決するためのコマンドを一覧表で確認しましょう。

症状・エラーメッセージ例主な原因即効解決コマンド・設定
invalid peer certificate: UnknownIssuer / certificate verify faileduv がWindows等のOS証明書ストアを参照せず、社内プロキシやセキュリティソフトのルート証明書を信頼できていないuv python install 3.12 --system-certs または環境変数 UV_SYSTEM_CERTS=true を設定
インストール完了後に python と打っても認識されない（またはMicrosoft Storeが開く）デフォルトでは python3.12 のようなバージョン付き実行ファイルのみ配置され、python.exe シムが作られていない・PATH未反映uv python install 3.12 --default を実行後、uv python update-shell を実行してターミナル再起動
No download found for request指定したバージョン文字列やアーキテクチャの表記ミス、または古い uv のバージョンリストを参照しているuv self update で本体を更新後、uv python list --all-versions で正確な名称を確認
Failed to download ... request or response body error / タイムアウトGitHub Releases（python-build-standalone）への通信がプロキシやファイアウォールで遮断されているHTTPS_PROXY 環境変数の設定、または UV_PYTHON_INSTALL_MIRROR の指定
Access is denied (os error 5) / os error 32既存の仮想環境やVS CodeがPythonプロセスを掴んでいる、またはアンチウイルスソフトの検疫ロックVS Codeや起動中のPythonプロセスを閉じてから uv python install --reinstall を実行

2. SSL証明書エラー（UnknownIssuer）で失敗する原因と対処法

WindowsのPowerShellや社内PCで uv python install 3.12 を実行した際、以下のようなエラーメッセージが表示されてダウンロードに失敗するケースが非常に多く報告されています。

error: Failed to download https://github.com/astral-sh/python-build-standalone/releases/download/...
  Caused by: Request failed after 3 retries
  Caused by: error sending request for url (...)
  Caused by: client error (Connect)
  Caused by: invalid peer certificate: UnknownIssuer

なぜブラウザでは繋がるのに uv だけSSLエラーになるのか？

最大の理由は、uv がデフォルトで採用しているTLS（暗号化通信）の検証仕組みにあります。

uv は高速性と移植性を高めるため、Rust製の暗号化ライブラリ（rustls）と、uv バイナリ自身に内蔵されたMozillaの標準ルート証明書セット（webpki-roots）をデフォルトで使用します。つまり、初期状態ではWindowsやmacOSの「OS標準の証明書ストア（システム証明書）」を参照しません。

そのため、以下のような環境では「知らない発行元の証明書（UnknownIssuer）」と判定されて通信が遮断されます。

  • 社内ネットワークでSSLインスペクション（Zscaler、Netskope、FortiGate、BlueCoat等によるHTTPS通信の復号・再暗号化）が行われており、社内独自のルート証明書がWindowsの証明書ストアに配布されている環境
  • 個人PCで「カスペルスキー」「ESET」「ノートン」「アバスト」などのセキュリティソフトの「HTTPSスキャン（暗号化接続の保護）」機能が有効になっており、セキュリティソフトのローカル証明書が挟まっている環境

解決策1：–system-certs フラグを付けて実行する（一時的・即効）

コマンド実行時に --system-certs（または短縮形 --native-tls）オプションを付与すると、uv は内蔵証明書ではなくWindowsやmacOSの「OS標準のシステム証明書ストア」を参照するようになります。

# OSのシステム証明書ストアを使ってPython 3.12をインストール
uv python install 3.12 --system-certs

また、現在のPowerShellセッション全体で有効にしたい場合は、環境変数 UV_SYSTEM_CERTS に "true" をセットしてから実行します。

# PowerShellで環境変数を設定して実行
$env:UV_SYSTEM_CERTS = "true"
uv python install 3.12

WSL2（Ubuntu等のBash環境）で同様のエラーが出る場合は、以下のコマンドで実行できます。

UV_SYSTEM_CERTS=true uv python install 3.12

解決策2：uv.toml に system-certs = true を記述して永続化する（推奨）

毎回 --system-certs オプションを入力するのは手間がかかるうえ、uv sync や uv add でパッケージをインストールする際にも同じSSLエラーが発生します。そのため、ユーザー共通の設定ファイルである uv.toml に設定を書き込んで永続化しておくのが最もおすすめです。

Windows（PowerShell）での永続設定手順

Windowsでは %APPDATA%\uv\uv.toml（具体的には C:\Users\<ユーザー名>\AppData\Roaming\uv\uv.toml）にファイルを配置します。以下のコマンドをPowerShellにコピー＆ペーストして実行すると、フォルダ作成から設定書き込みまで自動で完了します。

# 設定ディレクトリを作成して uv.toml に system-certs = true を書き込む
$uvConfigDir = "$env:APPDATA\uv"
New-Item -ItemType Directory -Force -Path $uvConfigDir | Out-Null
Set-Content -Path "$uvConfigDir\uv.toml" -Value "system-certs = true`n" -Encoding UTF8

作成された %APPDATA%\uv\uv.toml の中身は以下の1行だけです。

system-certs = true

WSL2（Linux）/ macOS での永続設定手順

LinuxやmacOSでは ~/.config/uv/uv.toml に設定を記述します。

mkdir -p ~/.config/uv
echo "system-certs = true" >> ~/.config/uv/uv.toml

解決策3：独自のCA証明書ファイル（.pem / .crt）を直接指定する場合

WSL2環境など、Windows側の証明書ストアには社内証明書が入っているものの、WSL2（Ubuntu）側の証明書ストアには登録されていないケースでは、証明書ファイル（.pem または .crt）のパスを環境変数 SSL_CERT_FILE で直接指定することで解決できます。

# カスタムCA証明書ファイルのパスを指定してインストール
SSL_CERT_FILE=/path/to/company-root-ca.crt uv python install 3.12

3. インストールしたのに python コマンドが使えない（PATHが通らない）時の対処法

「uv python install 3.12 が正常に完了したのに、ターミナルで python --version と打つとエラーになる（またはWindowsのMicrosoft Store画面が勝手に開いてしまう）」という問題も、初心者が必ずと言っていいほどつまずくポイントです。

原因：デフォルトではバージョン付きコマンドしか配置されない仕様

uv は既存のシステム環境を誤って壊さないよう、通常の uv python install 3.12 を実行しただけでは、%USERPROFILE%\.local\bin（Windowsの場合）に python3.12.exe というバージョン番号付きの実行ファイルしか作成しません。つまり、番号なしの python や python3 というコマンド（シム）は自動生成されない仕様になっています。

プロジェクトフォルダ内で作業する場合は uv run python main.py のように uv run を経由して呼び出すのが基本ですが、ターミナルから直接 python コマンドを叩きたい場合は以下の2ステップを実行します。

解決手順1：–default フラグを付けて python コマンドを有効化する

--default オプションを付けて uv python install を実行すると、python3.12 だけでなく、汎用コマンドである python および python3 の実行ファイルも %USERPROFILE%\.local\bin に作成されます。

# Python 3.12 をデフォルトの python / python3 コマンドとして配置する
uv python install 3.12 --default

※以前のバージョンの uv では --preview フラグが必要でしたが、現行バージョンでは --default のみで正式にサポートされています。もしエラーになる場合は、先に uv self update で uv 本体を最新版に更新してください。

解決手順2：uv python update-shell で環境変数 PATH を自動登録する

次に、uv がPython実行ファイルを配置したディレクトリ（Windowsでは C:\Users\<ユーザー名>\.local\bin、Linux/macOSでは ~/.local/bin）をOSの環境変数 PATH に登録します。

手動でシステムのプロパティ画面を開く必要はなく、以下の専用コマンドを実行するだけで自動設定されます。

# シェルの環境変数 PATH に uv の Python 実行ディレクトリを追加
uv python update-shell

コマンド実行後、変更された PATH を反映させるために、現在開いているPowerShell（またはWindows Terminal）を一度すべて閉じてから開き直してください。

再起動後、以下のコマンドで無事に uv 管理下のPythonが呼ばれているか確認します。

# バージョン確認
python --version

# どのパスの python.exe が呼ばれているか確認（Windows PowerShell）
(Get-Command python).Source

出力結果が C:\Users\<ユーザー名>\.local\bin\python.exe になっていれば成功です。

注意点：Windowsで Microsoft Store が勝手に開く場合の対策

もし uv python update-shell を実行しても python と入力した際にMicrosoft Storeが起動してしまう場合は、Windows標準の「アプリ実行エイリアス」が .local\bin よりも優先されてしまっています。

  1. キーボードの Win + I キーを押してWindowsの「設定」を開きます。
  2. 「アプリ」＞「アプリの詳細設定」＞「アプリ実行エイリアス」を開きます。
  3. 一覧の中にある「アプリ インストーラー（python.exe）」と「アプリ インストーラー（python3.exe）」の2つのスイッチを「オフ」に切り替えます。

これでWindows標準のダミーエイリアスが無効化され、uv でインストールしたPythonが確実に優先されるようになります。

4. プロキシ環境やGitHubダウンロード制限でタイムアウトする時の対処法

uv python install は、Astral社がメンテナンスしているGitHubリポジトリ（https://github.com/astral-sh/python-build-standalone）からビルド済みPythonバイナリをダウンロードします。そのため、社内プロキシの認証が必要な環境や、GitHub Releasesへのアクセスが制限されている環境では接続タイムアウトが発生します。

解決策1：プロキシ環境変数（HTTPS_PROXY）を設定する

プロキシサーバー経由で通信する必要がある場合は、HTTPS_PROXY 環境変数を設定してから実行します。

# PowerShellでプロキシを指定する例
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
# 認証が必要な場合： "http://username:password@proxy.example.com:8080"

uv python install 3.12 --system-certs

解決策2：社内ミラーや代替URL（UV_PYTHON_INSTALL_MIRROR）を指定する

セキュリティポリシーにより github.com への直接アクセスが禁止されており、社内のファイルサーバーやArtifactory等にPythonのアーカイブをミラーリングしている場合は、環境変数 UV_PYTHON_INSTALL_MIRROR または uv.toml の python-install-mirror 設定でダウンロード元URLを差し替えることができます。

# uv.toml でのミラー指定例
python-install-mirror = "https://mirror.example.com/python-build-standalone"

5. 権限エラー（os error 5 / os error 32）やファイル破損で失敗する時の対処法

Pythonのバージョンアップや再インストール時に、Access is denied (os error 5) や プロセスはファイルにアクセスできません。別のプロセスが使用中です (os error 32) というエラーが出る場合があります。

原因と解決手順

Windowsでは、実行中の .exe ファイルや .dll ファイルを上書き・削除できない仕様になっています。たとえば、VS CodeのPython拡張機能やJupyterカーネル、バックグラウンドのFastAPIサーバーなどが uv 管理下のPythonを起動したままになっていると、ファイルの置き換え時にロックエラーが発生します。

  1. VS CodeやPyCharmなどのエディタ、および別タブで開いているターミナルを一度すべて閉じます。
  2. タスクマネージャー（Ctrl + Shift + Esc）を開き、残っている python.exe プロセスがあれば終了させます。
  3. 新しくPowerShellを開き、--reinstall オプションを付けてクリーンに再インストールします。
# 壊れたキャッシュや中途半端な配置をクリーンにして再インストール
uv python install 3.12 --reinstall

また、ダウンロード途中のネットワーク切断でアーカイブキャッシュ自体が破損している場合は、uv cache clean でキャッシュを消去してから再実行すると正常に完了します。

まとめ

uv python install で発生するエラーは、原因の仕組みさえ分かってしまえばシンプルな設定で根本解決できます。

  • SSL証明書エラー（UnknownIssuer）が出る場合：uv がOS標準の証明書ストアを参照していないことが原因。uv python install 3.12 --system-certs を実行するか、%APPDATA%\uv\uv.toml（Linux/macOSは ~/.config/uv/uv.toml）に system-certs = true を追記して永続化する。
  • インストール後に python コマンドが使えない場合：uv python install 3.12 --default で汎用コマンド（python / python3）を作成し、uv python update-shell で PATH を通してからターミナルを再起動する。
  • WindowsでMicrosoft Storeが起動してしまう場合：Windowsの設定から「アプリ実行エイリアス」の python.exe / python3.exe をオフにする。
  • ファイルロックエラー（os error 5 / 32）が出る場合：VS Code等のエディタを閉じた状態で uv python install 3.12 --reinstall を実行する。

一度 uv.toml の証明書設定と PATH 設定を済ませておけば、以降は uv ならではの圧倒的なスピードで複数バージョンのPythonを自在に切り替えられるようになります。

次に読むおすすめ記事

無事にPython本体がインストールできたら、次はプロジェクトの作成（uv init）やパッケージ追加（uv add）の実践に進みましょう。基本フローとコマンド逆引きは以下の記事で詳しくまとめています。

参考情報