URL
type
status
date
slug
summary
tags
category
icon
password
🚀 uv是什么？
uv 是 Rust 写的「一站式 Python 项目管理器」，将原本需要 pip + venv + pip-tools + pyenv 等多个工具才能完成的任务整合成一条命令，且速度提升 10-100 倍。🧩 它到底能干啥？
传统做法 | 用 uv一条命令搞定 | 说明 |
pyenv install 3.12 | uv python install 3.12 | 下载 & 安装 CPython |
python -m venv .venv | uv venv | 创建虚拟环境 |
pip install -r requirements.txt | uv sync | 安装依赖并锁定版本 |
pip install requests | uv add requests | 加依赖并自动写入锁文件 |
pip-compile+pip-sync | uv lock/uv sync | 生成并同步锁定文件 |
pip install black && black . | uvx black . | 零安装运行一次性工具 |
pip list --tree | uv tree | 可视化依赖树 |
⚡ 核心优势
- 极速：并行解析 + Rust 实现，比
pip快 10-100 倍。
- 一体化：集成包管理、虚拟环境、Python 版本控制和脚本运行功能。
- 零配置：自动识别
pyproject.toml、requirements.txt，无迁移成本。
- 可锁定：默认生成
uv.lock，确保团队/CI 环境 100% 一致。
🎯 典型场景
- 新项目快速启动：
uv init→uv add flask→uv run app.py
- 老项目无缝迁移：将
requirements.txt放入目录，执行uv sync即可
- CI/CD 环境：一行
uv sync --frozen秒级还原完整环境
- 临时工具使用：
uvx ruff format .用完即走，无需全局安装
一句话记住：
uv = Python 生态的 "cargo" —— 有了它，Python 开发也能像 Rust 一样丝滑。
🚀 从零开始，用 uv 打造全新 Python 项目
0️⃣ 安装 uv（一次性）
平台 | 一行命令 |
macOS / Linux | curl -LsSf <https://astral.sh/uv/install.sh> \| sh |
Windows PowerShell | powershell -ExecutionPolicy ByPass -c "irm <https://astral.sh/uv/install.ps1> \| iex" |
验证
1️⃣ 创建项目骨架
目录一览
2️⃣ 虚拟环境 & 激活
提示符变成
(.venv) ✅3️⃣ 依赖管理（日常三板斧）
目的 | 命令 |
添加运行时依赖 | uv add requests fastapi |
添加开发工具 | uv add --dev pytest ruff |
锁定并同步 | uv sync |
4️⃣ 写代码
推荐结构
示例
src/demo_proj/main.py5️⃣ 运行 & 开发工作流
6️⃣ 打包 & 发布（可选）
7️⃣ 一键复现（给同事 / CI）
📌 命令速查表
任务 | 一行命令 |
切换 Python 版本 | uv python pin 3.11 |
导出 requirements.txt | uv export -o requirements.txt |
查看依赖树 | uv tree |
清理缓存 | uv cache clean |
🎉 完成！
你已经拥有了一个「可运行、可测试、可打包、可复现」的现代 Python 项目。
🚀 修改镜像源为国内常用pypi源
1️⃣ 全局配置（所有项目生效）
平台 | 配置文件路径 | 一键创建目录 |
Windows | %APPDATA%\\uv\\uv.toml | mkdir %APPDATA%\\uv |
Linux / macOS | ~/.config/uv/uv.toml | mkdir -p ~/.config/uv |
🔹 常用镜像源模板-公共源（腾讯 + 阿里 + 清华）
2️⃣ 项目级配置（仅当前项目生效）
将以下内容写入项目根目录的
pyproject.toml：3️⃣ 临时指定（命令行一次性）
🔍 查看当前配置
💡 小贴士
- 全局配置适合个人开发机；
- 项目配置便于团队协作；
- 命令行临时指定适合 CI/CD 或一次性测试。
🚀 使用 uv 从本地 CPython 安装包安装 Python
如果你想完全离线或使用本地已下载的 CPython 安装包（如
.tar.gz 或 .zip），uv 支持通过本地路径安装，以下是完整步骤：🔧 步骤一：准备本地安装包
- 从 https://github.com/astral-sh/python-build-standalone/releases 下载对应系统的 CPython 安装包，如：
- 放入本地目录，例如：
🔧 步骤二：设置环境变量（告诉 uv 使用本地包）
Windows（PowerShell）：
Linux/macOS：
⚠️ 注意路径格式必须是 file:// + 绝对路径，且不能指向 .tar.gz 文件本身，而是所在目录。
🔧 步骤三：安装指定版本
此时
uv 会从你指定的本地目录查找对应版本的安装包，不会联网下载。✅ 可选：配置为全局默认（不依赖环境变量）
你也可以在项目的
pyproject.toml 中添加：🧪 验证是否成功
输出中应包含你刚安装的版本，如：
📌 总结一句话
设置 UV_PYTHON_INSTALL_MIRROR=file:///路径 后，uv python install <版本> 就会优先使用本地 CPython 安装包，无需联网。
🚀 使用 uv 设置默认的 Python 版本
✅ 场景 1：为整个系统设置默认 Python（全局）
uv python install：安装指定版本（如果还没安装）。
uv python pin：在当前用户目录下创建一个默认版本链接，后续所有项目默认使用该版本。
⚠️ 该命令会在你的用户目录下创建一个 ~/.local/share/uv/python 的符号链接，影响所有未指定 Python 版本的项目。
✅ 场景 2：为某个项目设置默认 Python（推荐）
进入项目根目录后执行：
这会在项目根目录下创建
.python-version 文件：以后在该目录下运行
uv run 或 uv sync 时，都会自动使用该版本。🔍 查看当前默认版本
输出示例：
🧹 取消默认设置（仅项目级）
📌 一句话总结
- 全局默认：
uv python pin 3.12.4（用户级）
- 项目默认：进入项目目录后
uv python pin 3.12.4（创建.python-version）