uv 虚拟环境实战：创建、激活与版本控制

激活与停用虚拟环境

创建好后，需要激活才能生效。激活后终端提示符会带上环境名，比如 (.venv)。

Linux 和 macOS

• Bash/Zsh:

  source .venv/bin/activate
  

• Fish:

  source .venv/bin/activate.fish
  

• Csh/Tcsh:

  source .venv/bin/activate.csh
  

• Nushell:

  use .venv/bin/activate.nu
  

Windows

• CMD:

  .venv\Scripts\activate.bat
  

• PowerShell:

  .venv\Scripts\Activate.ps1
  

退出环境很简单，所有 Shell 通用：

deactivate

Python 版本管理高级技巧

查看可用版本

想知道有哪些版本能下？

uv python list

想看特定系列：

uv python list 3.12
uv python list pypy

安装特定版本

有时候不想等创建环境时再下载，可以先预装好。

uv python install 3.11.6
uv python install 3.12
uv python install pypy

升级与偏好设置

uv 支持升级已安装的 Python 到最新补丁版（注意：目前仅支持预览特性，且不支持 PyPy）。

uv python upgrade 3.12

配置文件中可以设定优先级，比如优先用系统自带的还是 uv 管理的：

# 配置文件设置
uv config set python-preference system
# 命令临时指定
uv venv --python 3.12 --no-managed-python

可选值包括 managed（默认）、only-managed、system、only-system。

自动发现与运行

uv 有个很实用的功能叫自动发现。即使不激活环境，只要在当前目录或其父目录有 .venv，很多命令都能识别。

使用 uv run

不用激活也能跑脚本，这在 CI 或临时测试时特别方便。

uv run python script.py
uv run pip list

还可以传参：

uv run -- python script.py --arg

配合 --project 指定目录搜索范围：

uv --project /path/to/project run python script.py

高级配置与缓存

配置文件

通过 uv.toml 可以定制行为，比如默认 Python 版本、是否自动下载等。

[python]
default-version = "3.12"
preference = "managed"
downloads = "automatic"

[venv]
directory = ".venv"
auto-activate = false

固定项目版本

在项目根目录放一个 .python-version 文件，内容只有一行版本号。uv 会自动读取并应用。

3.12.3

缓存管理

uv 会缓存下载的 Python 和包，清理缓存可以用：

uv cache dir
uv cache clean
uv cache clean --python

常见问题排查

问题 1：创建环境时报找不到 Python 版本 检查列表是否包含该版本：uv python list。如果确实没有，允许自动下载：uv venv --python 3.12 --allow-downloads，或者手动安装：uv python install 3.12。

问题 2：IDE 无法识别虚拟环境 大多数 IDE 需要手动指向解释器路径。比如在 VS Code 中，通过命令面板选择 Python 解释器，然后找到 ./.venv/bin/python (Mac/Linux) 或 ./.venv/Scripts/python.exe (Windows)。

问题 3：版本升级失败 注意 uv 目前主要支持补丁版本升级（如 3.12.1 -> 3.12.2）。如果是小版本跨越（3.11 -> 3.12），建议新建环境迁移数据。

小结

uv 把虚拟环境管理从'麻烦事'变成了'顺手活'。通过 uv venv 快速初始化，利用 --python 锁定版本，配合 uv run 免激活运行，再加上配置文件固化环境，开发体验会有质的提升。随着项目迭代，记得定期清理缓存，保持磁盘清爽。