uv 虚拟环境实战：5 步完成创建、激活与 Python 版本管理

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv

项目 A 钉死 Python 3.10，项目 B 要 3.12，两个 venv 反复切换，某次pip install手滑装进全局环境，包开始互相打架。uv 虚拟环境把这套流程压成一条命令：建环境、找版本、下载缺失的 Python，全自动。

三分钟跑通：安装、建环境、激活

这节给一条最短链路：确认 uv 可用 → 建环境 → 激活，三分钟进状态。

没装过 uv 的话，先按 安装文档 跑一遍官方安装脚本，然后：

uv --version

输出版本号即安装成功。

uv venv

在当前目录建一个默认的.venv。没指定--python时 uv 自己挑可用解释器，缺版本会直接下载装好，不用你操心。

source .venv/bin/activate

激活完成，提示符前出现(.venv)，python、pip全部指向环境内部。退出环境时输入一次deactivate即可，所有 shell 通用。

顺带看一眼速度，热缓存下各工具依赖解析耗时的对比（uv 的柱子几乎贴地）：

按需定制环境：名称、路径与 --python 的写法

默认.venv只够一个项目用；要换位置、换版本，看这节。

uv venv myenv

建一个名为myenv的环境，位置仍是当前目录。

uv venv /opt/envs/data-env

建在任意指定路径，参数写绝对路径或相对路径都行。

--python接受多种写法，一张表收齐：

实现名大小写不敏感：CPython 写作cpython或cp，PyPy 是pypy或pp，GraalPy 是graalpy或gp。几个典型组合：

uv venv --python 3.12.3 uv venv --python '>=3.10,<3.13' uv venv --python pypy

如果请求的版本本机没有，uv 默认会自动下载（python-downloads默认值automatic），下载完直接建环境。

Python 版本一键管理

这节把解释器本身交给 uv：查版本、装版本、升补丁，以及"用系统的还是用 uv 下的"。

uv python list

列出已安装和可下载的全量版本。

uv python list 3.12

按请求过滤，只看 3.12 系列；加--only-installed则只显示本机已装的。

uv python install 3.12.3

装精确补丁版本；把3.12.3换成3.12就是装该系列最新补丁，也可以一次装多个：uv python install 3.9 3.10 3.11。

uv python upgrade 3.12

把 3.12 升到最新补丁位，旧版本会保留（别的环境可能还在用）。不带参数则升级所有已装版本。注意：upgrade 只支持 uv 自管的 CPython，且只升补丁位，PyPy、GraalPy 不在范围内。

python-preference控制 uv 找解释器时的偏好，四种取值：

写进uv.toml即长期生效；单次命令可用--managed-python/--no-managed-python临时覆盖。更多规则见 Python 版本文档。

各 shell 激活命令的差异全在下面这张表，照着抄就行：

免激活运行：自动发现 + uv run

不想每次开终端先敲 activate？这节讲 uv 怎么自己找到环境。

uv 按以下顺序搜索虚拟环境：

1. VIRTUAL_ENV指向的已激活环境
2. CONDA_PREFIX指向的 Conda 环境
3. 当前目录或最近父目录中的.venv
4. 都没有时，提示你先跑uv venv

所以只要目录里有.venv，下面的命令开箱即用：

uv run python app.py

自动发现.venv并执行；依赖不全时会先同步再跑。

uv run -- my_script.py --flag

--之后的参数原样传给脚本，不会被 uv 误吞。

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

--project显式指定项目目录，环境搜索从那里开始。多个项目共用一个终端时不用来回cd。

项目级配置：uv.toml、.python-version 与缓存

这节把散在命令行的参数固化成项目配置，并管好用缓存。

# uv.toml python-preference = "managed" python-downloads = "automatic"

uv.toml和pyproject.toml里的[tool.uv]表等价，两者同时存在时uv.toml优先；完整设置清单见 配置文件文档。

.python-version文件则是团队级的版本锚点，内容就一行：

3.12.3

uv 从当前目录向上逐级查找该文件，找到就用它作为默认版本请求；uv python pin可一键生成。提交进仓库后，新同事第一次uv venv就会拿到和你一模一样的解释器。

缓存管理四条常用命令：

uv cache dir uv cache clean uv cache clean ruff uv cache prune

分别对应：打印缓存目录、清空全部缓存、只清单个包、只清过期条目。怀疑缓存过期时，任意安装命令追加--refresh强制重新校验。冷缓存与热缓存的安装耗时差距，直接看图：

避坑指南

踩得最多的五个坑，统一按"现象 → 原因 → 解决"排好。

1. ⚠️ 版本找不到

• 现象：uv venv --python 3.13报找不到匹配版本。
• 原因：本机没装且自动下载被禁（python-downloads = "manual"）；或者 uv 当前版本的 Python 清单里还没有它——清单随 uv 发布冻结，新版 Python 得先升 uv。
• 解决：uv python list确认可否下载；清单没有就先升级 uv，有的话手动uv python install 3.13。

2. 激活脚本报"不存在"

• 现象：source .venv/bin/activate提示 no such file。
• 原因：shell 和脚本不匹配（Fish 用了 sh 版脚本），或在 Windows 上敲了 Unix 路径。
• 解决：对照"Python 版本一键管理"一节的表格选对脚本。

3. 小版本升不上去

• 现象：uv python upgrade 3.12拒绝跳到 3.13。
• 原因：upgrade 只覆盖补丁位（3.12.1 → 3.12.4），且仅限 uv 自管的 CPython；跨小版本会影响依赖解析，uv 不替你做这个决定。
• 解决：补丁升级照常用；换小版本就新建环境。

4. IDE 看不到环境里的包

• 现象：uv run一切正常，IDE 里 import 直接红。
• 原因：IDE 选的解释器是系统 Python，不是环境里的。
• 解决：把解释器指到.venv/bin/python。VS Code 按 Ctrl+Shift+P 搜 "Python: Select Interpreter"，PyCharm 在 Settings 的 Python Interpreter 里选 Existing environment。

5. 升级了还是旧版本

• 现象：uv pip install --upgrade显示装好了，运行仍加载旧代码。
• 原因：缓存命中了旧 wheel。
• 解决：先uv cache clean <包名>再重装，或命令直接加--refresh。

回到主线：uv venv建环境、--python定版本、deactivate退出；uv run免激活跑命令，--project切项目；版本交给uv python list/install/upgrade，偏好写进uv.toml。

延伸阅读（仓库内文档）：

• 虚拟环境与自动发现
• Python 版本完整参考
• 缓存机制
• 配置文件
• uv run 用法

你的 uv 虚拟环境踩过什么坑？评论区聊聊。

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv