Windows 10/11 上 Pyenv-win 完整安装教程（含避坑指南）Windows 10/11 安装 pyen

Windows 10/11 安装 pyenv-win 完整教程（避坑版）

解决多 Python 版本冲突 | 自定义安装路径 | 全终端通用

前言

在 Windows 上开发 Python 项目时，经常会遇到不同项目需要不同 Python 版本的问题（比如项目A用 3.10，项目B用 3.12）。

pyenv-win 是 Windows 平台最稳定的 Python 版本管理工具，可以实现：

一台电脑同时安装多个 Python 版本
全局/目录/终端自由切换版本
不污染系统环境，与 conda 互不冲突

本文记录完整安装流程、踩坑实录、脚本修改、常用命令，新手可直接照做。

一、安装前准备

卸载/清理旧版 Python、conda 干扰
关闭所有终端，打开全新 PowerShell
允许运行脚本（解决权限报错）

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

二、官方安装脚本（默认安装到 C 盘）

官方一键安装命令：

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\你的用户名\.pyenv

三、重点问题：无法自定义安装路径？（坑点实录）

问题描述

无论怎么设置 $env:PYENV_WIN_HOME="S:\pyenv"，脚本依然强制安装到 C 盘用户目录。

根本原因

查看官方安装脚本发现：

$PyEnvDir = "${env:USERPROFILE}\.pyenv"

路径被硬编码！变量不生效！

四、自定义路径安装（修改脚本版，100% 成功）

1. 先彻底卸载旧版

# 删除安装目录
Remove-Item -Recurse -Force $HOME\.pyenv

并删除系统环境变量中的 PYENV/PYENV_ROOT 相关配置。

2. 使用修改后的安装脚本（安装到 S 盘）

将以下代码保存为 install-pyenv-win-modified.ps1：

<#
    .SYNOPSIS
    Installs pyenv-win to S:\pyenv (自定义路径)

    .DESCRIPTION
    已修改安装路径，默认安装到 S:\pyenv
#>

param (
    [Switch]$Uninstall = $False
)

# ====================== 自定义安装路径 ======================
$PyEnvDir = "S:\pyenv"
# ============================================================

$PyEnvWinDir = "${PyEnvDir}\pyenv-win"
$BinPath = "${PyEnvWinDir}\bin"
$ShimsPath = "${PyEnvWinDir}\shims"

Function Remove-PyEnvVars() {
    $PathParts = [System.Environment]::GetEnvironmentVariable('PATH', "User") -Split ";"
    $NewPathParts = $PathParts.Where{ $_ -ne $BinPath }.Where{ $_ -ne $ShimsPath }
    $NewPath = $NewPathParts -Join ";"
    [System.Environment]::SetEnvironmentVariable('PATH', $NewPath, "User")

    [System.Environment]::SetEnvironmentVariable('PYENV', $null, "User")
    [System.Environment]::SetEnvironmentVariable('PYENV_ROOT', $null, "User")
    [System.Environment]::SetEnvironmentVariable('PYENV_HOME', $null, "User")
}

Function Remove-PyEnv() {
    Write-Host "Removing $PyEnvDir..."
    If (Test-Path $PyEnvDir) {
        Remove-Item -Path $PyEnvDir -Recurse
    }
    Write-Host "Removing environment variables..."
    Remove-PyEnvVars
}

Function Get-CurrentVersion() {
    $VersionFilePath = "$PyEnvDir\.version"
    If (Test-Path $VersionFilePath) {
        $CurrentVersion = Get-Content $VersionFilePath
    }
    Else {
        $CurrentVersion = ""
    }
    Return $CurrentVersion
}

Function Get-LatestVersion() {
    $LatestVersionFilePath = "$PyEnvDir\latest.version"
    (New-Object System.Net.WebClient).DownloadFile("https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/.version", $LatestVersionFilePath)
    $LatestVersion = Get-Content $LatestVersionFilePath
    Remove-Item -Path $LatestVersionFilePath
    Return $LatestVersion
}

Function Main() {
    If ($Uninstall) {
        Remove-PyEnv
        If ($? -eq $True) { Write-Host "卸载成功" }
        exit
    }

    $CurrentVersion = Get-CurrentVersion
    If ($CurrentVersion) {
        $LatestVersion = Get-LatestVersion
        If ($CurrentVersion -eq $LatestVersion) {
            Write-Host "已是最新版本"
            exit
        }
        Remove-Item -Path $PyEnvDir -Recurse
    }

    New-Item -Path $PyEnvDir -ItemType Directory -Force | Out-Null
    $DownloadPath = "$PyEnvDir\pyenv-win.zip"
    (New-Object System.Net.WebClient).DownloadFile("https://github.com/pyenv-win/pyenv-win/archive/master.zip", $DownloadPath)
    Expand-Archive -Path $DownloadPath -DestinationPath $PyEnvDir
    Move-Item -Path "$PyEnvDir\pyenv-win-master\*" -Destination "$PyEnvDir"
    Remove-Item -Path "$PyEnvDir\pyenv-win-master" -Recurse
    Remove-Item -Path $DownloadPath

    # 设置环境变量
    [System.Environment]::SetEnvironmentVariable('PYENV', "${PyEnvWinDir}\", "User")
    [System.Environment]::SetEnvironmentVariable('PYENV_ROOT', "${PyEnvWinDir}\", "User")
    [System.Environment]::SetEnvironmentVariable('PYENV_HOME', "${PyEnvWinDir}\", "User")

    $PathParts = [System.Environment]::GetEnvironmentVariable('PATH', "User") -Split ";"
    $NewPathParts = ($BinPath, $ShimsPath) + $PathParts.Where{ $_ -ne $BinPath }.Where{ $_ -ne $ShimsPath }
    $NewPath = $NewPathParts -Join ";"
    [System.Environment]::SetEnvironmentVariable('PATH', $NewPath, "User")

    Write-Host "`n✅ pyenv-win 安装成功！安装路径：$PyEnvDir"
    Write-Host "🔧 请重启终端生效`n"
}

Main

3. 运行脚本

.\install-pyenv-win-modified.ps1

4. 验证安装

pyenv --version

出现版本号即成功。

五、pyenv-win 常用基本命令（全终端通用）

1. 查看信息

pyenv --version             # 查看 pyenv 版本
pyenv versions              # 查看已安装的 Python
pyenv install --list        # 查看可安装版本
pyenv which python          # 查看当前 Python 路径

2. 安装/卸载 Python

pyenv install 3.12.2        # 安装 Python 3.12.2
pyenv uninstall 3.10.0      # 卸载版本
pyenv rehash                # 刷新环境（安装后自动执行）

3. 切换版本（最重要）

pyenv global 3.12.2         # 全局默认版本
pyenv local 3.11.9          # 当前目录专用版本
pyenv shell 3.10.14         # 当前终端临时版本
pyenv local --unset         # 取消目录版本

4. 验证版本

python --version
pip --version

六、常见问题汇总

1. 安装后 CMD 不生效

解决：把以下路径加入系统环境变量 Path

S:\pyenv\pyenv-win\bin
S:\pyenv\pyenv-win\shims

2. `pyenv root` 报错

原因：Windows 版不支持此命令

替代：

$env:PYENV_ROOT
pyenv which python

3. 安装 Python 慢/失败

解决：开启代理，或手动下载安装包放入：

S:\pyenv\pyenv-win\install_cache

4. 与 conda 冲突吗？

完全不冲突，pyenv 管理版本，conda 管理环境。

七、总结

pyenv-win 是 Windows 最佳 Python 版本管理器
默认脚本路径硬编码，必须手动修改才能自定义路径
修改脚本第 28 行即可实现任意目录安装
支持 PowerShell / CMD / Git Bash 全终端通用
常用命令简单好记，切换版本一键完成

按照本文流程安装，可彻底告别 Python 版本混乱问题。

Windows 10/11 上 Pyenv-win 完整安装教程（含避坑指南）