Python 多版本管理最佳实践，包括 Windows、Linux (Debian) 传统方案以及新兴工具 uv 的使用指南。

核心原则

无论在哪个平台，现代 Python 开发的铁律：

  1. 隔离项目：每个项目必须有独立的虚拟环境 (.venv)。
  2. 隔离工具：全局命令行工具（如 black, ruff）不装在系统 Python 里，而是用 pipx 或 uv tool 管理。
  3. 不污染系统：尽量不动操作系统的默认 Python（尤其是 Linux）。

1. Windows 环境最佳实践

Windows 的核心优势是官方提供的 Python Launcher (py.exe)。

  • 多版本管理：

  • 安装：推荐使用 winget install Python.Python.3.12 或官网 python.org 安装包。务必勾选 “Install launcher for all users”。

  • 切换：使用 py 命令调度。

  • py -0p：列出所有版本。

  • py -3.12：使用特定版本。

  • 项目流程：

# 1. 指定版本创建环境
py -3.12 -m venv .venv
# 2. 激活虚拟环境
.\.venv\Scripts\Activate.ps1
# 若因执行策略被拦截，可临时放行本进程：
# Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
# 3. 安装依赖
pip install -r requirements.txt
# 设置代理
$env:HTTPS_PROXY="http://proxy.example.com:8080"
pip install -r requirements.txt
# 编码/中文路径问题：在 PowerShell 里先执行 `chcp 65001`（切到 UTF-8）可能有帮助

以项目 myproj 为例（默认用最高版本 3.12；老项目按需换版本）。

# 1) 选择解释器版本（用 py.exe）
py -3.12 -V
# 2) 创建并激活虚拟环境（每个项目一个）
py -3.12 -m venv .venv
# PowerShell 激活
.\.venv\Scripts\Activate.ps1
# （CMD 则是 .\.venv\Scripts\activate.bat）
# 3) 升级 pip 并安装依赖
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
# 或：python -m pip install fastapi uvicorn[standard]
# 4) 运行项目
python -m your_package_or_main

切换 Python 版本：删除 .venv，用 py -3.10 -m venv .venv 重新建环境即可（依赖会按 requirements 重装）。

2. Linux (Debian) 环境最佳实践

Linux 的核心痛点是系统依赖（apt 等工具依赖 /usr/bin/python3），绝对不能随意替换或破坏。

  • 准备工作：必须先安装构建依赖（Build Essentials, SSL, FFI 等），否则编译 Python 会失败或缺模块。
sudo apt update
sudo apt install -y build-essential curl git ca-certificates \
  zlib1g-dev libssl-dev libffi-dev libreadline-dev libsqlite3-dev \
  libbz2-dev liblzma-dev libgdbm-dev libnss3-dev uuid-dev tk-dev
  • 多版本管理 (User Space)：
  • 推荐工具：pyenv (或 asdf)。
  • 作用：在用户目录 (~/.pyenv) 安装任意 Python 版本，不影响系统。
  • 命令：pyenv install 3.12.6 -> pyenv global 3.12.6 (全局默认) -> pyenv local 3.10 (目录级锁定)。
# 1) 安装 pyenv
curl https://pyenv.run | bash

# 2) 写入 shell 初始化（bash 示例；zsh 同理改为 ~/.zshrc）
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
exec $SHELL   # 重新加载 shell

# 3) 安装多个 Python 版本（示例）
pyenv install 3.12.6
pyenv install 3.10.14

# 4) 设定默认与项目内版本
pyenv global 3.12.6           # 整机默认用 3.12
cd ~/code/myproj
pyenv local 3.10.14           # 该项目固定用 3.10（目录下生成 .python-version）

常用命令： pyenv versions（列版本） · pyenv which python（看路径） · pyenv uninstall 3.x.y（卸载）

  • 项目流程：
# pyenv 会自动识别目录下的 .python-version
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# 列出可装版本（pyenv）
pyenv install --list | grep 3.12

# 安装/卸载/切换
pyenv install 3.12.6
pyenv uninstall 3.10.14
pyenv local 3.12.6

# 新建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate

# 依赖管理
python -m pip install --upgrade pip
pip freeze > requirements.txt

# 全局 CLI
pipx install poetry
pipx ensurepath

3. 新一代全能工具：uv

uv 是由 Rust 编写的极速工具，旨在替代 pip, pip-tools, pipx, poetry, pyenv 的大部分功能。

  • 安装：curl -LsSf https://astral.sh/uv/install.sh | sh

  • 核心组件：

  • uv：项目依赖管理、Python 版本管理。

  • uv python install 3.12：自动下载并管理 Python 版本（无需 pyenv）。

  • uv venv / uv pip install：极速创建环境和装包。

  • uv run pytest：在隔离环境中运行命令。

  • uvx (等同于 uv tool run)：临时/一次性运行工具。

  • 场景：不想安装，只想跑一下。

  • 例：uvx cowsay "hello"

  • uv tool install：永久安装全局工具。

  • 场景：安装 CLI 工具并暴露到 PATH。

  • 支持 Git 安装：uv tool install git+https://github.com/user/repo.git@main (类似 pipx，但在隔离环境中构建)。

卸载

先 uv tool list 看它登记的工具名，再：

uv tool uninstall <name>

（名字以 uv tool list 显示为准）

总结对照表

场景 传统方案 (Windows) 传统方案 (Linux) 现代方案 (uv)
Python 版本管理 winget + py.exe pyenv / asdf uv python install
虚拟环境创建 py -m venv python -m venv uv venv
安装依赖 pip install pip install uv pip install / uv sync
全局 CLI 工具 pipx pipx uv tool install
一次性运行 pipx run pipx run uvx

建议路径：

  1. 如果只是维护旧项目，沿用 OS 传统方案（Windows 用 py，Linux 用 pyenv）。
  2. 如果是新项目或追求速度，强烈推荐拥抱 uv，它统一了上述所有工作流。