uv 安装、国内镜像配置与项目初始化 - 教程

uv 安装、国内镜像配置与项目初始化

一、uv 工具安装与验证

uv 是一款高性能 Python 项目管理工具，支持依赖管理、虚拟环境创建、Python 版本管理等功能，相比 pip+venv 速度更快。

1. 安装 uv（分操作系统）

macOS/Linux 系统

# 通过官方脚本安装，自动适配系统并配置环境变量
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows 系统

# 需管理员权限，通过 PowerShell 执行官方安装脚本
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 验证安装是否成功

安装完成后，通过以下命令确认 uv 可正常使用：

# 查看 uv 版本（若输出版本号，说明安装成功）
uv --version

3. 升级 uv 到最新版

# 升级 uv 自身（确保获取最新功能和 bug 修复）
uv self update

4. 安装指定 Python 版本（可选）

uv 可直接管理多个 Python 版本，按需安装：

# 查看 uv 支持的所有 Python 版本（包括稳定版和测试版）
uv python list
# 安装 Python 3.12（示例，可替换为其他版本如 3.11）
uv python install 3.12
# 更新 shell 配置，让系统识别新安装的 Python（生效需重启终端）
uv python update-shell

二、国内镜像源配置（加速依赖下载）

默认的 PyPI 源在国内访问较慢，配置国内镜像可大幅提升依赖安装速度。

1. 全局镜像配置（推荐，一劳永逸）

全局配置后，所有项目默认使用指定镜像，无需重复设置。

步骤1：找到配置文件路径

• Linux/macOS：~/.config/uv/config.toml
• Windows：%USERPROFILE%\.config\uv\config.toml（如 C:\Users\你的用户名\.config\uv\config.toml）

步骤2：创建/编辑配置文件

# Linux/macOS：用 vim 打开（若文件不存在会自动创建）
vim ~/.config/uv/config.toml
# Windows：用记事本打开
notepad %USERPROFILE%\.config\uv\config.toml

步骤3：添加镜像源配置

在配置文件中写入以下内容（选择一个镜像即可）：

# 阿里云镜像（推荐，稳定性好）
[registries.pypi]
index = "https://mirrors.aliyun.com/pypi/simple/"
# 可选：清华大学镜像（学术网络友好）
# [registries.tuna]
# index = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# 可选：豆瓣镜像（备用）
# [registries.douban]
# index = "https://pypi.doubanio.com/simple/"

2. 临时使用镜像源（单次生效）

若仅需某次操作使用特定镜像，可通过 --index 参数指定：

# 安装 requests 时临时用阿里云镜像
uv add requests --index https://mirrors.aliyun.com/pypi/simple/
# 同步环境依赖时临时用清华镜像
uv sync --index https://pypi.tuna.tsinghua.edu.cn/simple/

3. 验证镜像配置是否生效

# 查看当前配置的镜像源（确认是否正确设置）
uv config show | grep index
# 测试安装一个依赖（如 numpy），观察终端输出的下载地址是否为镜像源
uv add numpy

三、项目初始化与基础操作

使用 uv 初始化项目，规范管理依赖和运行脚本。

1. 创建项目目录并进入

# 创建项目文件夹（名称自定义，这里以 my_uv_project 为例）
mkdir my_uv_project && cd my_uv_project

2. 初始化项目（生成核心配置文件）

# 初始化项目，同时指定 Python 版本为 3.12（-p 是 --python 的简写）
# 执行后会生成 pyproject.toml（项目核心配置文件）
uv init -p 3.12

3. 理解核心配置文件：pyproject.toml

该文件是项目的"身份证"，包含项目信息、依赖管理、工具配置等，示例配置如下：

[project]
name = "my_uv_project"  # 项目名称（小写字母+短横线）
version = "0.1.0"       # 版本号（遵循语义化版本：主版本.次版本.修订号）
authors = [
  { name="你的名字", email="your@email.com" }  # 作者信息
]
requires-python = ">=3.12"  # 项目支持的最低 Python 版本
# 自定义运行脚本（通过 uv run <脚本名> 执行）
[tool.uv.scripts]
start = "python main.py"  # 示例：运行主程序（需手动创建 main.py）
test = "pytest"           # 示例：运行测试（需安装 pytest）
# uv包管理器配置
[[tool.uv.index]]
# 使用清华大学PyPI镜像源以提高下载速度
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# 设置为默认索引
default = true

4. 安装项目依赖

uv 区分「生产依赖」（项目运行必需）和「开发依赖」（仅开发阶段使用，如测试工具）。

安装生产依赖

# 示例：安装 FastAPI（Web 框架）和 uvicorn（服务器）
# 多个依赖用空格分隔，uv 会自动解析依赖关系并安装
uv add fastapi "uvicorn[standard]"

安装开发依赖

# 示例：安装 pytest（测试框架）和 requests（HTTP 库）作为开发依赖
# --dev 表示依赖仅用于开发环境，不会打包到生产环境
uv add --dev pytest requests

5. 验证项目环境

# 查看项目依赖树（展示所有已安装依赖及其版本、依赖关系）
uv tree
# 验证依赖是否安装成功（以 pytest 为例，检查版本）
uv run pytest --version

四、高级配置（可选）

自定义依赖缓存和 Python 安装路径，适合多环境隔离场景。

1. 修改依赖缓存路径

默认缓存路径：~/.cache/uv（Linux/macOS）或 %USERPROFILE%\.cache\uv（Windows），可自定义：

# Linux/macOS：临时生效（永久生效需添加到 .bashrc 或 .zshrc）
export UV_CACHE_DIR=/home/你的用户名/opt/uv/cache
# Windows：临时生效（永久生效需添加到系统环境变量）
set UV_CACHE_DIR=D:/dev/uv/cache

2. 修改 Python 安装路径

默认安装路径：~/.local/share/uv/python（Linux/macOS）或 %USERPROFILE%\.local\share\uv\python（Windows），可自定义：

# Linux/macOS：临时生效
export UV_PYTHON_INSTALL_DIR=/home/你的用户名/opt/uv/python
# Windows：临时生效
set UV_PYTHON_INSTALL_DIR=D:/dev/uv/python

总结

通过以上步骤，可完成 uv 的安装、镜像配置和项目初始化。核心流程为：
安装 uv → 配置国内镜像（加速下载）→ 初始化项目 → 安装依赖 → 验证环境

uv 的优势在于速度快、配置简洁，适合替代传统的 pip+venv 组合，尤其适合国内网络环境下的 Python 项目开发。