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接受多种写法一张表收齐写法示例含义精确版本3、3.12、3.12.3缺补丁位时取该系列最新版版本范围3.10,3.13满足范围的最高可用版本只写实现cpython、pypy该实现的最新版实现版本cpython3.12指定实现 版本缩写拼接cp312、pp310实现名缩写直接接版本号实现名大小写不敏感CPython 写作cpython或cpPyPy 是pypy或ppGraalPy 是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 找解释器时的偏好四种取值取值行为managed默认优先 uv 自管版本但系统已有的仍优先于新下载only-managed只用 uv 自管版本忽略系统 Pythonsystem优先系统 Pythononly-system只用系统 Python写进uv.toml即长期生效单次命令可用--managed-python/--no-managed-python临时覆盖。更多规则见 Python 版本文档。各 shell 激活命令的差异全在下面这张表照着抄就行系统Shell激活命令Linux/macOSBash/Zsh/shsource .venv/bin/activateLinux/macOSFishsource .venv/bin/activate.fishLinux/macOSCsh/Tcshsource .venv/bin/activate.cshLinux/macOSNushelluse .venv/bin/activate.nuWindowsCMD.venv\Scripts\activate.batWindowsPowerShell.venv\Scripts\Activate.ps1免激活运行自动发现 uv run不想每次开终端先敲 activate这节讲 uv 怎么自己找到环境。uv 按以下顺序搜索虚拟环境VIRTUAL_ENV指向的已激活环境CONDA_PREFIX指向的 Conda 环境当前目录或最近父目录中的.venv都没有时提示你先跑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 automaticuv.toml和pyproject.toml里的[tool.uv]表等价两者同时存在时uv.toml优先完整设置清单见 配置文件文档。.python-version文件则是团队级的版本锚点内容就一行3.12.3uv 从当前目录向上逐级查找该文件找到就用它作为默认版本请求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 按 CtrlShiftP 搜 Python: Select InterpreterPyCharm 在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考