uv python版本管理、虚拟环境管理、包管理器 作者：马育民 • 2026-05-04 20:08 • 阅读：10002 # 介绍 `uv` 是由 Astral 公司（Ruff 工具作者）开发、Rust 编写的**极速 Python 包与项目管理器**，可一站式替代 `pip`、`venv`、`pyenv`、`pipx` 等工具，核心优势是**比 pip 快 10–100 倍**、依赖解析强、一体化环境管理。 ### 什么是 uv？ - **极速包安装器**：替代 `pip`，解析与安装速度提升**一个数量级**（冷启动快 8–10 倍，缓存后快 80–115 倍）。 - **虚拟环境管理器**：替代 `venv`/`virtualenv`，自动创建与管理 `.venv`。 - **Python 版本管理器**：替代 `pyenv`，一键安装/切换多版本 Python。 - **项目管理器**：类似 `Poetry`/`PDM`，支持 `pyproject.toml` + `uv.lock` 标准化依赖管理。 - **工具运行器**：替代 `pipx`，隔离环境安装并执行 CLI 工具（`uvx`）。 ### 优势 - **🚀 速度碾压**：Rust 底层 + 并行下载 + PubGrub 解析算法，大型项目安装从**分钟级降至秒级**。 - **📦 一体化工具**：一个命令行搞定**环境、依赖、版本、脚本运行**，无需多工具切换。 - **🔒 可复现性强**：跨平台 `uv.lock` 文件，保证**开发/测试/生产环境完全一致**。 - **🧩 兼容现有生态**：无缝支持 `requirements.txt`、`pyproject.toml`、`setup.py`，迁移零成本。 - **💾 智能缓存**：三级缓存（元数据/下载/构建），重复安装**几乎瞬时完成**。 ### 为什么选择 uv？ `uv` 的核心优势在于其革命性的速度和强大的功能集成。 * **极致的速度**：得益于 Rust 的并行处理能力和高效的依赖解析算法，`uv` 在安装包、解析依赖和创建虚拟环境等操作上比传统工具快 10 到 100 倍。 * **统一的工作流**：它将多个工具的功能整合于一身，让你无需在 `pip`、`venv`、`pip-tools`、`pipx`、`pyenv` 等多个工具间切换，大大简化了开发环境。 * **开箱即用**：`uv` 是一个独立的二进制文件，无需 Python 环境即可安装和运行，避免了“先有鸡还是先有蛋”的安装难题。它遵循“约定优于配置”的原则，默认行为就能满足大部分需求。 ### 为什么这么快？ #### 1. Rust 语言底层 - 无 GC 开销、内存占用低、执行效率接近 C++。 #### 2. PubGrub 依赖解析算法 - 替代 pip 传统回溯算法，时间复杂度从**指数级降至 O(n²)**，冲突定位更精准。 #### 3. 并行下载与解压 - 同时下载多个包、并行解压，最大化利用网络与 CPU。 #### 4. 三级缓存架构 - **元数据缓存**：缓存包索引信息，避免重复请求 PyPI。 - **下载缓存**：缓存 `.whl`/`.tar.gz` 包，重复安装直接复用。 - **构建缓存**：缓存编译后的扩展包（如 `numpy`），避免重复编译。 --- ### 与主流工具对比 #### 1. uv vs pip + venv | 特性 | uv | pip + venv | | :--- | :--- | :--- | | 速度 | 快 10–100 倍 | 慢，大型项目分钟级 | | 环境管理 | 一体化，自动创建 | 需手动创建/激活 | | 锁文件 | 原生支持 `uv.lock` | 需 `pip freeze`，无统一标准 | | 依赖解析 | PubGrub，冲突清晰 | 回溯算法，冲突信息模糊 | #### 2. uv vs Poetry - **速度**：uv 比 Poetry **快 5–10 倍**（Poetry 解析慢）。 - **兼容性**：uv 无缝支持 `requirements.txt`，Poetry 强绑定 `pyproject.toml`。 - **功能**：Poetry 内置打包/发布，uv 目前专注**环境与依赖管理**（后续会支持）。 #### 3. uv vs Conda - **定位**：uv 专注**纯 Python 包**；Conda 管理**跨语言依赖**（如 C 库、CUDA）。 - **速度**：uv 解析/安装**远快于 Conda**（Conda 用 SAT 求解器，复杂度高）。 - **适用场景**：uv 适合 Web/后端/数据分析（纯 Python）；Conda 适合**科学计算/机器学习**（需系统库）。 # 快速安装-windows系统 - uv安装到默认路径 `C:\Users\你的用户名\.uv\` - 安装python的默认路径：`C:\Users\你的名字\.uv\python` - uv 下载的所有包缓存的默认路径：`C:\Users\你的名字\.cache\uv` - uv 安装的工具（ruff、black、jupyter）默认路径：`C:\Users\你的名字\.uv\tools` ### 方式一：独立安装（推荐，无需 Python 环境） 启动 **PowerShell**（执行PowerShell脚本），执行下面命令： ``` powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` 1. `powershell` 意思：**启动 Windows 的 PowerShell 命令行工具** 2. `-ExecutionPolicy ByPass` 意思：**临时允许运行远程脚本，不拦截安全提示** Windows 默认不让随便运行网上下载的脚本，这句就是**临时放行**，只对这一条命令有效，非常安全。 3. `-c "..."` 意思：**执行引号里的内容** 4. `irm https://astral.sh/uv/install.ps1` - `irm` = `Invoke-RestMethod` - 意思：**去这个网址下载 uv 的安装脚本** - 相当于：**打开网页 → 复制安装代码** 5. `| iex` - `|` = 管道，把前面的结果传给后面 - `iex` = `Invoke-Expression` - 意思：**立即执行刚才下载的安装脚本** 整句话连起来的意思 **让 PowerShell 临时放行安全限制 → 下载 uv 安装脚本 → 直接运行安装** 就是**一键自动安装 uv**，不需要你手动下载、点下一步、配置环境变量，全部自动完成。 ### 方式二：通过 pip 安装（已有 Python） ```bash pip install uv # 或 pipx（隔离环境） pipx install uv ``` ### 验证安装是否成功 另启动shell窗口，执行下面命令： ```bash uv --version ``` 输出版本号，如下图，表示成功： [](https://www.malaoshi.top/upload/0/0/1GW3FpQ8xA48.png) # 快速安装-macOS/Linux 系统 ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` # 高级安装-windows 安装到指定路径 如：安装到 `D:\devtools\uv` 路径，启动 **PowerShell**，执行下面命令： ``` powershell -ExecutionPolicy ByPass -c {$env:UV_INSTALL_DIR = "D:\devtools\uv";irm https://astral.sh/uv/install.ps1 | iex} ``` ### 修改默认路径 安装后，在系统环境变量（用户变量）里加 3 个变量： | 变量名 | 示例值 | |---|---| | UV_PYTHON_INSTALL_DIR | `D:\devtools\uv_python` | | UV_CACHE_DIR | `D:\devtools\uv_cache` | | UV_TOOL_DIR | `D:\devtools\uv_tools` | **解释：** - `UV_PYTHON_INSTALL_DIR`：uv 下载安装的 Python 保存路径 - `UV_CACHE_DIR`：uv 下载的所有包缓存路径 - `UV_TOOL_DIR`：uv 安装的工具（ruff、black、jupyter）的路径 ### 查看配置路径是否成功 另开启一个 shell，执行下面命令，看输出的路径是不是上面环境变量的： ``` uv python dir ``` ``` uv cache dir ``` ``` uv tool dir ``` # 更新uv 一键更新 uv ``` uv self update ``` # 指定国内源 安装python、库时，默认从国外服务器下载，有时速度很慢，甚至网络不稳定导致下载一半中断，要改为国内源 ### 永久设置国内源（推荐） 配置后，安装python、库时，永久使用国内源 在文件夹地址栏输入下面路径： ``` %APPDATA% ``` 敲回车，编程下面路径： ``` C:\Users\mym\AppData\Roaming ``` 查看该目录下是否有下面文件夹，没有就创建： ``` uv ``` 在 `%APPDATA%\uv` 目录下，创建 `uv.toml` 文件，内容如下： ``` # 配置 Python 解释器下载源 python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone/" # 配置 PyPI 包下载源 (例如：阿里云) [[index]] url = "https://mirrors.aliyun.com/pypi/simple/" default = true ``` ### 国内常用源列表 ``` 阿里：https://mirrors.aliyun.com/pypi/simple/ 华为：https://mirrors.huaweicloud.com/pypi/simple/ 腾讯云：https://mirrors.cloud.tencent.com/pypi/simple/ ``` ### 临时用一次国内源（单次有效） ```powershell uv install --index-url https://pypi.tuna.tsinghua.edu.cn/simple/ ``` ```powershell uv add requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple/ ``` ### 查看是否设置成功 打开一个新的终端窗口（确保加载了最新配置）。 运行以下命令（以安装 numpy 为例）： ```bash pip install numpy --verbose ``` **注意：**加上 `--verbose` 可以看到更详细的调试信息。 观察输出内容： ✅ 生效了： 你会看到类似 `Using index url: https://mirrors.aliyun.com/pypi/simple/` 的提示，或者下载链接显示的是 `mirrors.aliyun.com` ❌ 没生效： 如果显示 `pypi.org` 或者下载速度极慢，说明配置未命中。 # Python 版本管理 ### 列出可下载、已安装版本 ``` uv python list ``` [](https://www.malaoshi.top/upload/0/0/1GW3Fpq7BzAi.png) ### 安装指定 Python 版本 **注意：**配置上面的环境变量后，要重新开一个shell窗口，否则不生效 自动解压到缓存目录 安装 3.11.9 ```bash uv python install 3.11.15 ``` 安装 3.10.x ``` uv python install 3.10 ``` ### 切换项目 Python 版本 写入 .python-version ``` uv python pin 3.11.9 ``` # 常用命令 ### 1. 初始化项目 初始化项目（生成 pyproject.toml + .python-version） ```bash uv init my_project ``` [](https://www.malaoshi.top/upload/0/0/1GW3FqwdzgXS.png) 自动创建 `my_project` 目录，如下图： [](https://www.malaoshi.top/upload/0/0/1GW3FqxQOTFZ.png) ### 2. 创建虚拟环境 ``` cd my_project ``` 手动创建虚拟环境（默认 .venv） ```bash uv venv .venv ``` 在 `my_project` 目录下自动创建 `.venv` 目录，如下图： [](https://www.malaoshi.top/upload/0/0/1GW3Fr4c6Zty.png) ### 3. 激活环境 ##### Windows ``` .venv\Scripts\activate ``` ##### macOS/Linux ``` source .venv/bin/activate ``` ##### 查看python版本 ``` python ``` [](https://www.malaoshi.top/upload/0/0/1GW3FrAcYNhR.png) ### 4. 退出环境 ``` deactivate ``` # 查看已安装的依赖 ``` uv pip list ``` # 添加依赖 **作用：**安装 + 写入依赖文件（正式用法） 运行后会自动做 3 件事： 1. 安装 requests 2. 自动把包名写到 pyproject.toml 3. 生成 / 更新版本锁文件（保证别人装的版本和你一样） **适合：**开发项目、正式工程、要保存依赖的场景 ### 添加生产依赖 ##### 添加最新版的依赖 ``` uv add requests ``` ##### 指定版本 ``` uv add requests==2.31.0 ``` ##### 安装「不低于某个版本」 ``` uv add "requests>=2.30.0" ``` ##### 安装「不高于某个版本」 ``` uv add "requests<=2.30.0" ``` ### 添加开发依赖 如测试工具 ``` uv add --dev pytest ``` ### 同步环境 安装 `pyproject.toml` 里的所有依赖 ``` uv sync ``` ### 锁定依赖（生成/更新 uv.lock，提交到版本库） ``` uv lock ``` # 移除依赖 ``` uv remove requests tqdm ``` # 运行脚本 ``` uv run app.py ``` ### 传递参数 ``` uv run app.py --epochs 50 --batch-size 32 ``` ### 直接用指定版本运行脚本 ``` uv run --python 3.11.9 app.py ``` # 包管理（不推荐） **作用：**只安装，不保存（临时用法） 运行后： 1. 只安装包 2. 不会写入 pyproject.toml 3. 下次别人克隆项目，不会自动装这些包 **适合：**临时测试、临时用一下、不想保存依赖 ```bash # 安装包（同 pip，底层极速解析） uv pip install numpy pandas ``` ### 生成 requirements.txt 兼容旧项目 ``` uv pip freeze > requirements.txt ``` ### 从 requirements.txt 安装 ``` uv pip install -r requirements.txt ``` ### 卸载包 ``` uv pip uninstall numpy ``` ### 清空所有包 **注意：**只是清空所有包，不会修改 `pyproject.toml` 文件中的依赖 ``` uv pip uninstall --all ``` # 工具运行（uvx，替代 pipx） ```bash # 无需安装，直接运行 CLI 工具（隔离环境） uvx ruff check . # 运行 ruff 代码检查 uvx black main.py # 运行 black 格式化 # 安装工具到隔离环境 uv tool install ruff uv tool run ruff check . # 或直接 ruff check .（加入 PATH） ``` --- # 高级用法 ### 1. 锁文件严格模式（CI/CD 必备） ```bash # 强制使用锁文件，不更新（CI 环境防意外升级） uv sync --locked # 仅更新锁文件，不安装 uv lock --upgrade # 升级所有依赖 uv lock --upgrade-package requests # 升级指定包 ``` ### 2. Monorepo 工作区（多项目管理） ```toml # 根目录 pyproject.toml [tool.uv.workspace] members = ["libs/*", "apps/*"] # 包含子项目 resolver = "highest" # 统一依赖版本 ``` ```bash # 安装所有子项目依赖 uv sync --workspace # 为指定子项目添加依赖 uv add requests --project libs/core ``` ### 3. 脚本内联依赖（快速脚本） 在 Python 脚本头部添加注释声明依赖，`uv run` 自动安装： ```python # /// script # dependencies = ["requests==2.31.0", "pandas==2.1.0"] # /// import requests import pandas as pd # 代码逻辑... ``` ```bash uv run main.py # 自动创建临时环境、安装依赖、运行脚本 ``` --- # 迁移（从 pip/Poetry 到 uv） ### 1. 从 pip + requirements.txt 迁移 ```bash # 1. 初始化项目 uv init # 2. 导入 requirements.txt uv add -r requirements.txt # 3. 生成锁文件 uv lock # 4. 后续用 uv sync 替代 pip install ``` ### 2. 从 Poetry 迁移 ```bash # 1. 导出 Poetry 依赖 poetry export -f requirements.txt --output requirements.txt # 2. 同上述步骤导入 uv ``` --- # 总结 `uv` 是 Python 包管理的**革命性工具**，以**极速性能、一体化功能、无缝兼容性**解决了传统工具的核心痛点。对于**新项目**，直接用 `uv init` 开始；对于**旧项目**，可逐步迁移（兼容 `requirements.txt`）。目前（2026 年 4 月）uv 已更新到 **0.11.8**，功能稳定，适合生产环境使用。 原文出处：http://malaoshi.top/show_1GW3FqUl5rYM.html