🐍

【pyenv-win/uv】Windows上にPython環境を構築する

に公開
Python
pyenv
tech

１．はじめに

本記事では pyenv-win と uv を使用してWindows上にPython環境を構築します。

■ pyenv-win でできること

pyenv-win を使用することで以下のことができます

  • Windows 環境で簡単に Python を導入することができる
  • 複数の Python のバージョンを管理／バージョンを切り替えることができる
  • バージョン毎に独自構成の仮想環境を作成できる

■ uv でできること

uv を使用することで以下のことができます

  • Python のバージョン毎に複数の仮想環境を作成できる

以上を図で表すとこんな感じです↓↓↓

本記事では以下を実施します。

  • pyenv-win の導入
  • pyenv-win を使って Python のバージョンを指定してインストールする
  • uv の導入
  • uv を使って Python 用仮想環境を作成する

２．pyenv-winの導入

以下をベースにpyenv-winを導入していきます。
https://github.com/pyenv-win/pyenv-win/blob/master/docs/installation.md#powershell

■ pyenv-winの導入方法

管理者権限で PowerShell を起動する。
以下コマンドで実行ポリシーを変更する。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine

以下コマンドで pyenv-win を導入する。

Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
実行時ログ
PS C:\Windows\system32> Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"                   

    ディレクトリ: C:\Users\ユーザ名


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        2024/08/03     18:10                .pyenv
pyenv-win is successfully installed. You may need to close and reopen your terminal before using it.

& : File C:\Users\ユーザ名\install-pyenv-win.ps1 cannot be loaded because running scripts is disabled on this system. For
more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:173
+ ... n.ps1" -OutFile "./install-pyenv-win.ps1"; &"./install-pyenv-win.ps1"
+ ~~~~~~~~~~~~~~~~~~~~~~~~~ 
 + CategoryInfo          : SecurityError: (:) [], PSSecurityException 
 + FullyQualifiedErrorId : UnauthorizedAccess

３．バージョンを指定してPythonをインストールする

ここでは、pyenv-win の導入ができていることを確認し、
実際にpyenv-winを使ってPythonをインストールします。

■ py-envの導入確認

pyenv-win が導入できていることを確認します。

PowerShell を再起動し以下実行する。
pyenv-winのバージョンが表示されれば導入完了。

PS C:\Windows\system32> pyenv --version
pyenv 3.1.1

■ インストール可能なPythonのバージョン確認

下記コマンドでインストール可能なPythonのバージョンリストを確認する。

pyenv install --list

■ Pythonのバージョンを指定してインストールする

以下コマンドでPythonのバージョンを指定してインストールできます。

pyenv install 3.11.9
実行時ログ
PS C:\Windows\system32> pyenv install 3.11.9
:: [Info] ::  Mirror: https://www.python.org/ftp/python
:: [Info] ::  Mirror: https://downloads.python.org/pypy/versions.json
:: [Info] ::  Mirror: https://api.github.com/repos/oracle/graalpython/releases
:: [Downloading] ::  3.11.9 ...
:: [Downloading] ::  From https://www.python.org/ftp/python/3.11.9/python-3.11.9-amd64.exe
:: [Downloading] ::  To   C:\Users\ユーザ名\.pyenv\pyenv-win\install_cache\python-3.11.9-amd64.exe
:: [Installing] ::  3.11.9 ...
:: [Info] :: completed! 3.11.9

■ 利用する Python のバージョンを指定する

下記コマンドで利用する Python のバージョンを指定する。

pyenv global 3.11.9

下記のように指定したPythonのバージョンが表示されれば完了。

PS C:\Windows\system32> pyenv global 3.11.9
PS C:\Windows\system32> python --version
Python 3.11.9

４．uv をインストールする

以下をベースに uv を導入していきます。
https://github.com/astral-sh/uv?tab=readme-ov-file#installation

■ uvの導入方法

PowerShellを起動し、下記コマンドで uv をインストールします。

powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
実行時ログ
$ powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
Downloading uv 0.8.14 (x86_64-pc-windows-msvc)
Installing to C:\Users\ユーザ名\.local\bin
  uv.exe
  uvx.exe
  uvw.exe
everything's installed!

To add C:\Users\ユーザ名\.local\bin to your PATH, either restart your shell or run:

    set Path=C:\Users\ユーザ名\.local\bin;%Path%   (cmd)
    $env:Path = "C:\Users\ユーザ名\.local\bin;$env:Path"   (powershell)

■ uv のパスを通す

下記コマンドで uv のパスを通します。

$env:Path = "C:\Users\ユーザ名\.local\bin;$env:Path"

※下記のようにWindowsの環境変数から直接通しても大丈夫です

■ uv の導入確認

パスを通した後、PowerShell を再起動し、下記コマンドで uv が導入できていることを確認します。

$ uv --version
uv 0.8.22 (ade2bdbd2 2025-09-23)

５．uv を使って仮想環境を作成する

Pythonで開発作業したいフォルダに移動します。

■ 仮想環境の作成

移動後、下記コマンドで仮想環境を作成できます。
※今回は仮想環境名を「.venv」として作成します

uv venv .venv

仮想環境が作成されると下記構造のフォルダが作成されます。
また、仮想環境名を変えることで複数個の仮想環境を作成できます。

.venv（仮想環境名）
├─Lib
│  └─site-packages：仮想環境配下で pip などでインストールしたライブラリ
└─Scripts：uv で使用するスクリプト
└─pyenv.cfg：仮想環境の設定ファイル

■ 仮想環境の有効化

下記コマンドで仮想環境を有効化できます。

.\.venv\Scripts\Activate.ps1

下記のように PowerShell の表記が変われば仮想環境の有効化ができています。
(.venv) PS C:\Users\ユーザ名\フォルダ名>

■ 仮想環境配下でライブラリをインストールする

仮想環境配下では下記のようにライブラリをインストールできます。※pipの例

uv pip install -r requirements.txt

Appendix

pyenv-winのインストールが失敗する場合

私の実行時には以下パターンで失敗しました。

  • 実行ポリシーが変更されていない（２の最初の手順）
  • VSCode上などでPowerShellが開かれていると失敗する場合がありました

また、pyenv-winが正常に動作しない場合は

  • 「C:\Users\ユーザ名\.pyenv」フォルダを削除して再インストールする。
  • 環境変数を再確認する

pyenv-winの環境変数について

変数名 変数値
Path C:\Users\ユーザ名\.pyenv\pyenv-win\bin
Path C:\Users\ユーザ名\.pyenv\pyenv-win\shims
PYENV C:\Users\ユーザ名\.pyenv\pyenv-win\
PYENV_HOME C:\Users\ユーザ名\.pyenv\pyenv-win\
PYENV_ROOT C:\Users\ユーザ名\.pyenv\pyenv-win\

pipのSSL設定

pipコマンドでライブラリインストール時に、SSL関連のエラーが出る場合、
以下コマンドでpipのSSＬ設定を行うことができます。

pip config set global.cert 証明書のパス

最新のPythonのバージョンがない場合はpyenv-winをアップデートする

Python3.13をインストールしようと、インストール可能なPythonのバージョンリストを確認したところ以下が得られた。
「3.13.a」や「3.13.b」があるが、「a」や「b」が付いていない「3.13.X」が表示されない。
※「3.13.Xa」や「3.13.Xb」などは、開発バージョンとのことなので基本的にはインストールしない。

$ pyenv install -l
3.13.0a1-win32
3.13.0a1-arm
3.13.0a1
3.13.0b4-win32
3.13.0b4-arm
3.13.0b4

この場合、pyenv-winをアップデートすることで、インストール可能なPythonのバージョンリストを更新することができる。

$ pyenv update
:: [Info] ::  Mirror: https://www.python.org/ftp/python
:: [Info] ::  Mirror: https://downloads.python.org/pypy/versions.json
:: [Info] ::  Mirror: https://api.github.com/repos/oracle/graalpython/releases
:: [Info] ::  Scanned 227 pages and found 791 installers.

更新後、再度リストを取得すると、「a」や「b」が付いていない「3.13.0」が増えていた。

$ pyenv install -l
3.13.0a1-win32
3.13.0a1-arm
3.13.0a1
3.13.0b4-win32
3.13.0b4-arm
3.13.0b4
3.13.0

Discussion