作者：evansremer
最后更新：2026-07-15
适用平台：Windows / Linux
用 uv 管理 Python 工程
前言
uv 是由 Astral 团队（Ruff 的开发者）用 Rust 编写的高性能 Python 包与项目管理工具。它统一了 pip、pip-tools、virtualenv、pyenv 和 poetry 的部分功能，速度比传统工具快。
本教程将带你从零开始，在 Windows 和 Linux 上完成 uv 的安装与项目配置。
1. 安装 uv
1.1 Windows 安装
方式一：PowerShell 一键安装（推荐）
按下 Win + R 键，输入 powershell，按回车打开终端，执行：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
安装完成后，验证版本：
uv --version
方式二：通过 Winget 安装
winget install --id=astral-sh.uv -e
方式三：使用 pip 安装
如果你已经有 Python 环境，也可以用 pip：
pip install uv
注意： 安装后如果终端提示找不到
uv命令，请重启终端或手动将%USERPROFILE%\.cargo\bin添加到系统环境变量PATH中。
1.2 Linux 安装
方式一：curl 脚本安装（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh
安装后刷新环境变量：
source $HOME/.cargo/env
uv --version
方式二：包管理器安装
macOS（Homebrew）：
brew install uv
Arch Linux：
pacman -S uv
Debian/Ubuntu（需要添加 Astral 源或使用 pip）：
pip install uv
提示： 对于服务器环境，也可以直接下载预编译二进制文件：
# 下载最新版本 curl -LsSf https://github.com/astral-sh/uv/releases/latest/download/uv-x86_64-unknown-linux-gnu.tar.gz | tar xz # 移动到 PATH 目录 sudo mv uv /usr/local/bin/
1.3 验证安装
uv --version
如果看到版本号，说明安装成功
2. 配置国内镜像源（加速下载）
在国内使用 uv 时，将默认的 PyPI 源替换为国内镜像可以显著提升依赖下载速度。uv 支持多种配置方式，按需选择即可。
2.1 方式一：设置环境变量（全局生效）
Windows（PowerShell）：
请直接复制下方所有代码，在 PowerShell 终端中一次性粘贴并回车运行
# 1. 创建配置目录（如果不存在）
New-Item -Path "$env:APPDATA\uv" -ItemType Directory -Force
# 2. 写入配置内容到 uv.toml (使用清华源)
$content = @"
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
"@
Set-Content -Path "$env:APPDATA\uv\uv.toml" -Value $content
Linux / macOS：
# 临时设置
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
# 持久化（写入 ~/.bashrc 或 ~/.zshrc）
echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/' >> ~/.bashrc
source ~/.bashrc
2.2 方式二：在 pyproject.toml 中配置（仅在项目生效，建议先阅读后面理解uv项目结构再回看此方法）
在项目根目录的 pyproject.toml 中追加以下内容，仅对当前项目生效、不影响全局：
[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
2.3 方式三：命令行参数（临时使用）
# 安装时临时指定镜像
uv pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple/ requests
# 或使用 --default-index
uv pip install --default-index https://pypi.tuna.tsinghua.edu.cn/simple/ requests
2.4 常用国内镜像站汇总
| 镜像站 | 地址 |
|---|---|
| 阿里云 | https://mirrors.aliyun.com/pypi/simple/ |
| 清华大学（推荐） | https://pypi.tuna.tsinghua.edu.cn/simple/ |
| 中国科学技术大学 | https://pypi.mirrors.ustc.edu.cn/simple/ |
| 腾讯云 | https://mirrors.cloud.tencent.com/pypi/simple/ |
| 华为云 | https://mirrors.huaweicloud.com/repository/pypi/simple/ |
| 豆瓣 | https://pypi.douban.com/simple/ |
建议： 阿里云镜像更新及时、稳定性好，日常开发首选。如果遇到包同步延迟（新版本未出现），可以临时切到清华源或中科大源。
2.5 验证镜像是否生效
# 查看当前生效的索引地址（需要 uv 0.5+）
uv pip compile --verbose 2>&1 | head -20
或者直接安装一个包，观察下载日志中的来源地址。
3. uv 能做什么
uv 的核心能力包括：
| 功能 | 命令 | 说明 |
|---|---|---|
| Python 版本管理 | uv python |
安装、切换 Python 版本 |
| 虚拟环境管理 | uv venv |
创建和激活虚拟环境 |
| 包安装 | uv pip install |
相比 pip 快 10 倍以上 |
| 项目初始化 | uv init |
快速创建新工程 |
| 依赖锁文件 | uv lock |
生成 uv.lock |
| 依赖同步 | uv sync |
根据锁文件安装精确版本 |
| 项目运行 | uv run |
在项目环境中运行命令 |
| 工具安装 | uv tool install |
全局安装 CLI 工具 |
4. 创建你的第一个 uv 项目
4.1 初始化项目
在终端中进入你的工作目录，执行：
uv init my-project
cd my-project
这会生成以下文件结构：
my-project/
├── .python-version # 指定 Python 版本
├── .venv/ # 虚拟环境（uv sync 时自动创建）
├── README.md
├── pyproject.toml # 项目配置和依赖声明
└── hello.py # 示例代码
4.2 pyproject.toml 说明
生成的项目配置文件看起来像这样：
[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []
这是 uv 项目的心脏——所有依赖、项目元数据都定义在这里。
4.3 安装 Python 版本
uv 可以自动下载和管理 Python 版本。如果你的系统没有 pyproject.toml 中指定的 Python 版本，uv 会自动下载。
你也可以手动安装：
# 列出可用的 Python 版本
uv python list
# 安装指定版本
uv python install 3.12
# 安装最新版本
uv python install
5. 管理项目依赖
5.1 添加依赖
# 添加运行时依赖
uv add requests numpy pandas
# 添加开发依赖
uv add --dev pytest black ruff
执行 uv add 后，pyproject.toml 自动更新，同时生成 uv.lock 锁文件。
5.2 移除依赖
uv remove requests
5.3 查看依赖树
uv tree
5.4 同步环境
# 安装 pyproject.toml 中声明的所有依赖（精确版本依据 uv.lock）
uv sync
# 只安装生产依赖，跳过开发依赖
uv sync --no-dev
6. 运行代码
6.1 使用 uv run
uv run 会在项目虚拟环境中执行命令，无需手动激活虚拟环境：
# 运行 Python 脚本
uv run hello.py
# 直接执行 Python 代码
uv run python -c "import numpy; print(numpy.__version__)"
# 运行 pytest
uv run pytest
6.2 手动激活虚拟环境
如果你更喜欢传统方式：
Windows：
.\.venv\Scripts\activate
Linux：
source .venv/bin/activate
建议： 优先使用
uv run——它自动处理环境激活，不会污染全局 Python 环境。
7. 全局工具管理
uv 还可以管理全局 CLI 工具，类似于 pipx：
# 安装工具（在独立环境中）
uv tool install ruff
# 运行已安装的工具
uv tool run ruff check .
# 列出已安装的工具
uv tool list
# 卸载工具
uv tool uninstall ruff
8. 在 VS Code 中使用 uv
VS Code 是目前最流行的 Python 开发编辑器之一，它可以无缝对接 uv 管理的 Python 环境。
8.1 选择 uv 创建的 Python 解释器
uv 创建的项目会在根目录生成 .venv 虚拟环境。在 VS Code 中打开一个uv管理的pyhton工程文件夹后，在右下角会出现如图所示的东东：“工程名(python解释器版本）”
点击一下就可以在上方复选框里面选择相应的pyhton解释器，一般路径里面含有你当前工程路径和.venv的就是当前虚拟环境了，vscode也会标出“推荐的项目”
8.2 在 VS Code 终端中使用 uv
VS Code 内置终端本身就是系统终端，按crtl + `（Esc下方的键）直接在终端面板中执行 uv 命令即可：
uv add <包名> # 安装依赖
uv remove <包名> # 卸载依赖
uv sync # 同步所有依赖
uv run python # 在项目环境中启动 Python
建议忽略 VS Code 自带的包管理 UI（基于 pip），统一在终端中使用 uv 管理依赖，保持一致性。
----至此，你已经可以轻松使用uv来管理你的python工程啦！（撒花）----
参考链接
本教程由 evansremer 编写，内容基于 uv 最新版本（2026 年 7 月）。如有更新，请以官方文档为准。若有错误，欢迎批评指正。
评论区