uv可直接按项目锁定Python版本：进入项目根目录执行uv python pin 3.12.0，自动生成.python-version文件，后续uv venv、uv run、uv sync等命令均自动匹配并优先使用该版本，未安装时会自动下载缓存。
uv 能直接按项目锁定 Python 版本，不需要 pyenv、不用手动激活环境、也不用改系统 PATH —— 只要执行 uv python pin，后续所有命令（uv venv、uv run、uv sync）都会自动用对版本。
怎么给项目绑定指定 Python 版本
进入项目根目录后，运行：uv python pin 3.12.0
这条命令会在当前目录生成一个 .python-version 文件，内容就是 3.12.0。之后你在该目录下执行任何 uv 命令，它都会优先找这个版本；如果还没装，就自动下载并缓存。
常见错误现象：
• 执行完 uv python pin 3.11 后，python --version 还是显示旧版本 → 这正常，uv 不修改全局 python 命令，只影响 uv 自己的命令链（如 uv run python -c "print(1)"）
• 报错 No Python version found for 3.11.9 → 说明该小版本未被官方索引收录，换 3.11（表示最新补丁版）或查 uv python list --all 看可用列表
使用场景：
• 多个老项目分别依赖 3.9.18、3.10.12、3.12.3，各自目录下运行一次 uv python pin 即可隔离
• CI 流水线里避免硬编码路径，直接靠 .python-version 驱动构建环境
立即学习“Python免费学习笔记（深入）”；
uv python install 和 uv python default 的区别
uv python install 是下载并本地安装某个 Python 解释器二进制；uv python default 是设置全局默认版本（写入 ~/.pyenv/version 类似位置），影响所有未 pin 的新项目。
参数差异：
• uv python install 3.11.6 → 下载精确小版本，适合需要复现某次生产环境的场景
• uv python install pypy3.10 → 支持 PyPy，但注意不是所有包（如 PyTorch）都提供 PyPy wheel
• uv python default 3.12 → 设置后，新项目不 pin 时会默认用 3.12；但已有项目的 .python-version 仍优先级更高
容易踩的坑：
• 在 WSL 或 macOS 上首次运行 uv python install 可能卡住 → 检查是否被公司代理拦截，可加 --no-cache 或配置 HTTP_PROXY
• uv python default 对已存在的虚拟环境无效 → 已创建的 .venv 不会自动重装解释器，得删掉重来
为什么 uv run python 能自动匹配项目版本
uv run 不是简单地调用系统 python，而是先读取当前目录的 .python-version，再定位对应解释器路径（比如 ~/.local/share/uv/python/3.12.0/install/bin/python），最后把参数透传过去。整个过程不污染 shell 环境变量，也无需 source .venv/bin/activate。
性能影响：
• 首次运行会触发解释器查找 + 虚拟环境初始化（如果还没建），耗时约 200–500ms；后续同项目内重复运行基本是毫秒级
• 如果项目没 .python-version，uv run python 会 fallback 到 uv python default 或系统 python，行为可预测
可验证方式：uv run which python → 输出路径应包含版本号子目录uv run python -c "import sys; print(sys.executable)" → 显示的路径必须和 uv python list 中已安装的某条一致
老项目迁移时怎么安全切换 Python 版本
已有 requirements.txt 或 pyproject.toml 的项目，不要直接删 .venv 后 pin —— 先确保新版本能跑通依赖解析。
推荐步骤：
• 运行 uv python pin 3.12（假设目标版本）
• 运行 uv pip compile requirements.in -o requirements.txt（如有 requirements.in）或 uv pip compile pyproject.toml -o uv.lock
• 观察输出里是否有 incompatible 提示；若有，说明某些包不支持 3.12，得降级或找替代
• 确认无误后，再 uv sync 创建新环境
容易忽略的点：
• uv.lock 文件是 Python 版本敏感的 —— 同一份 pyproject.toml 在 3.11 和 3.12 下生成的 uv.lock 可能不同，不能混用
• 某些 C 扩展包（如 numpy）在不同 Python 小版本间 wheel 不通用，uv sync 会自动选适配版本，但首次安装可能稍慢
