pyenv（Windows 下为 pyenv-win）是 Python 版本管理工具，核心解决多 Python 版本共存、版本冲突及环境不一致等问题，让用户在一台电脑上无缝切换不同 Python 版本，无需手动修改环境变量或卸载重装。
一、pyenv 的核心功能
1.1 多版本 Python 共存
手动管理多个 Python 版本时，需反复修改环境变量并记住不同版本的安装路径，极易混乱。pyenv 能实现：
- 一键安装 Python 2.7/3.6/3.10/3.12 等任意版本（包括 Anaconda、Miniconda、PyPy 等衍生版本）；
- 所有版本隔离存储在
~/.pyenv目录（Windows：%USERPROFILE%\.pyenv），互不干扰； - 无需卸载现有 Python，系统自带的 Python 也不会被修改或覆盖。
1.2 灵活切换版本
| 切换维度 | 作用范围 | 适用场景 |
|---|---|---|
| 全局版本 | 整个系统（所有目录） | 设置系统默认 Python 版本 |
| 局部版本 | 当前目录 + 子目录 | 项目专属版本 |
| 临时版本 | 仅当前终端会话 | 临时测试某个版本 |
1.3 隔离不同版本的依赖包
不同 Python 版本的 pip 包是完全隔离的，不会出现跨版本污染：
- 例如 Python 3.8 装 Django 4.0，Python 3.10 装 Django 5.0，两者互不影响；
- 解决升级一个版本的包导致另一个项目报错的问题。
1.4 无痛安装 / 卸载 Python 版本
- 安装：一行命令
pyenv install 3.10.11，自动下载、安装、配置； - 卸载：一行命令
pyenv uninstall 3.10.11，彻底删除该版本及对应依赖，无残留； - 若网络受限，可手动下载安装包到缓存目录，pyenv 会自动识别。
二、pyenv 安装
Windows 系统
powershell -ExecutionPolicy Bypass -Command "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"
如果已下载 install-pyenv-win.ps1 到 Downloads 目录，直接执行：
cd %USERPROFILE%\Downloads
powershell -ExecutionPolicy Bypass -File .\install-pyenv-win.ps1
脚本会自动将 pyenv-win 安装到 %USERPROFILE%\.pyenv\pyenv-win，并配置环境变量（PYENV_ROOT、PATH 添加 bin 和 shims 路径）。
若网络受限无法下载脚本，可直接保存以下内容为 install-pyenv-win.ps1：
<# .SYNOPSIS Installs pyenv-win .DESCRIPTION Installs pyenv-win to $HOME\.pyenv If pyenv-win is already installed, try to update to the latest version. .PARAMETER Uninstall Uninstall pyenv-win. Note that this uninstalls any Python versions that were installed with pyenv-win. .INPUTS None. .OUTPUTS None. .EXAMPLE PS> install-pyenv-win.ps1 .LINK Online version: https://pyenv-win.github.io/pyenv-win/ #>
param (
[Switch] $Uninstall = $False
)
$PyEnvDir = "${env:USERPROFILE}\.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 "pyenv-win successfully uninstalled." } Else { Write-Host "Uninstallation failed." }
exit
}
$BackupDir = "${env:Temp}/pyenv-win-backup"
$CurrentVersion = Get-CurrentVersion
If ($CurrentVersion) {
Write-Host "pyenv-win $CurrentVersion installed."
$LatestVersion = Get-LatestVersion
If ($CurrentVersion -eq $LatestVersion) { Write-Host "No updates available."; exit }
Else { Write-Host "New version available: $LatestVersion. Updating..."; Write-Host "Backing up existing Python installations..."; $FoldersToBackup = "install_cache", "versions", "shims"; ForEach ($Dir in $FoldersToBackup) { If (-not (Test-Path $BackupDir)) { New-Item -ItemType Directory -Path $BackupDir }; Move-Item -Path "${PyEnvWinDir}/${Dir}" -Destination $BackupDir }; Write-Host "Removing $PyEnvDir..."; Remove-Item -Path $PyEnvDir -Recurse }
}
New-Item -Path $PyEnvDir -ItemType Directory
$DownloadPath = "$PyEnvDir\pyenv-win.zip"
(New-Object System.Net.WebClient).DownloadFile("https://github.com/pyenv-win/pyenv-win/archive/master.zip", $DownloadPath)
Start-Process -FilePath "powershell.exe" -ArgumentList @( "-NoProfile", "-Command `"Microsoft.PowerShell.Archive\Expand-Archive -Path \`"$DownloadPath\`" -DestinationPath \`"$PyEnvDir\`"" ) -NoNewWindow -Wait
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 = $PathParts.Where{ $_ -ne $BinPath }.Where{ $_ -ne $ShimsPath }
$NewPathParts = ($BinPath, $ShimsPath) + $NewPathParts
$NewPath = $NewPathParts -Join ";"
[System.Environment]::SetEnvironmentVariable('PATH', $NewPath, "User")
If (Test-Path $BackupDir) { Write-Host "Restoring Python installations..."; Move-Item -Path "$BackupDir/*" -Destination $PyEnvWinDir }
If ($? -eq $True) { Write-Host "pyenv-win is successfully installed. You may need to close and reopen your terminal before using it." } Else { Write-Host "pyenv-win was not installed successfully. If this issue persists, please open a ticket: https://github.com/pyenv-win/pyenv-win/issues." }
}
Main
