uv 启动 Python 项目与配置镜像

本文以 FastAPI 项目为例，演示如何使用 uv 从零开始创建和管理 Python 项目，以及如何配置国内镜像源加速包下载。

1. Python 版本管理

在创建项目之前，先了解如何管理 Python 版本。

1.1 查看可用的 Python 版本

查看 uv 支持安装的所有 Python 版本：

uv python list

输出示例：

cpython-3.13.1-windows-x86_64-none    <download available>
cpython-3.12.8-windows-x86_64-none    <download available>
cpython-3.11.11-windows-x86_64-none   <download available>
cpython-3.10.16-windows-x86_64-none   <download available>
cpython-3.9.21-windows-x86_64-none    <download available>
cpython-3.8.20-windows-x86_64-none    <download available>

说明：

带 <download available> 表示可以下载但未安装
如果已安装会显示安装路径

1.2 查看本地已安装的 Python 版本

只查看已安装的版本：

uv python list --only-installed

输出示例：

cpython-3.12.8-windows-x86_64-none    C:\Users\zzy\.local\share\uv\python\cpython-3.12.8-windows-x86_64-none\python.exe
cpython-3.11.11-windows-x86_64-none   C:\Users\zzy\.local\share\uv\python\cpython-3.11.11-windows-x86_64-none\python.exe

1.3 安装指定 Python 版本

如果需要的版本未安装，可以使用 uv 自动下载安装：

uv python install 3.11

安装特定小版本：

uv python install 3.11.11

安装过程输出：

Searching for Python versions matching: Python 3.11
Found Python 3.11.11
Downloading Python 3.11.11
Installing Python 3.11.11
Python 3.11.11 installed successfully

1.4 查找 Python 解释器路径

查看当前使用的 Python 解释器：

uv python find

输出示例：

C:\Users\zzy\.local\share\uv\python\cpython-3.12.8-windows-x86_64-none\python.exe

2. 创建 FastAPI 项目

2.1 使用默认 Python 版本初始化

在你想要创建项目的位置，打开终端执行：

uv init fastapi-demo
cd fastapi-demo

命令解释：

uv init fastapi-demo：创建名为 fastapi-demo 的项目文件夹
自动生成 pyproject.toml 配置文件
自动生成示例文件 hello.py
使用系统默认或最新的 Python 版本

2.2 指定 Python 版本初始化（推荐）

如果项目需要特定 Python 版本：

uv init --python 3.11 fastapi-demo
cd fastapi-demo

或者使用精确版本：

uv init --python 3.11.11 fastapi-demo

说明：

如果指定的版本未安装，uv 会自动下载
项目的 pyproject.toml 会记录 Python 版本要求

2.3 查看项目配置

查看生成的 pyproject.toml 文件：

type pyproject.toml  # Windows
cat pyproject.toml   # macOS/Linux

默认内容示例：

[project]
name = "fastapi-demo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

注意：requires-python 字段指定了项目所需的最低 Python 版本。

2.4 生成的项目结构

fastapi-demo/
├── pyproject.toml    # 项目配置文件
├── hello.py          # 示例代码
└── README.md         # 项目说明

2.5 固定项目 Python 版本（可选）

如果希望项目始终使用特定版本的 Python：

uv python pin 3.11.11

效果：

在项目根目录生成 .python-version 文件
文件内容为：3.11.11
之后在该项目中运行 uv 命令会自动使用该版本

查看固定的版本：

type .python-version  # Windows
cat .python-version   # macOS/Linux

3. 配置镜像源（重要）

在国内使用 PyPI 官方源下载包会很慢，建议先配置国内镜像源。

2.1 方式一：项目级配置（推荐）

编辑项目中的 pyproject.toml 文件，在末尾添加：

[[tool.uv.index]]
name = "tsinghua"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

其他可用镜像源：

# 阿里云
url = "https://mirrors.aliyun.com/pypi/simple"

# 腾讯云
url = "https://mirrors.cloud.tencent.com/pypi/simple"

# 中国科技大学
url = "https://pypi.mirrors.ustc.edu.cn/simple"

# 豆瓣
url = "https://pypi.douban.com/simple"

2.2 方式二：全局配置

如果希望所有项目都使用镜像源，可以配置全局设置。

Windows 系统：

创建或编辑文件 %APPDATA%\uv\uv.toml（通常是 C:\Users\你的用户名\AppData\Roaming\uv\uv.toml）

mkdir %APPDATA%\uv
notepad %APPDATA%\uv\uv.toml

在文件中添加：

index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

macOS/Linux 系统：

创建或编辑文件 ~/.config/uv/uv.toml

mkdir -p ~/.config/uv
nano ~/.config/uv/uv.toml

添加相同内容：

index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

2.3 方式三：临时使用镜像

如果只想在某次安装时使用镜像，可以使用 --index-url 参数：

uv add fastapi --index-url https://pypi.tuna.tsinghua.edu.cn/simple

4. 安装 FastAPI 依赖

4.1 添加 FastAPI 和 Uvicorn

uv add fastapi
uv add "uvicorn[standard]"

命令解释：

uv add fastapi：安装 FastAPI 框架
uv add "uvicorn[standard]"：安装 Uvicorn ASGI 服务器（带标准扩展）
依赖会自动写入 pyproject.toml 的 dependencies 字段
同时生成或更新 uv.lock 锁定文件，确保依赖版本一致
自动创建 .venv 虚拟环境（如果不存在）
自动安装依赖到虚拟环境

安装过程输出示例：

Resolved 10 packages in 1.2s
Downloaded 10 packages in 2.3s
Installed 10 packages in 45ms
 + annotated-types==0.6.0
 + anyio==4.3.0
 + fastapi==0.110.0
 + ...

重要文件说明：

pyproject.toml：记录项目依赖（人类可读）
uv.lock：锁定精确版本（机器生成，不要手动编辑）
.venv/：虚拟环境目录（不要提交到 Git）

一次性添加多个依赖：

uv add fastapi "uvicorn[standard]" pydantic-settings

4.2 查看已安装的依赖

uv pip list

或者查看 pyproject.toml 文件：

[project]
name = "fastapi-demo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.110.0",
    "uvicorn[standard]>=0.27.0",
]

5. 编写 FastAPI 应用

5.1 创建主程序文件

删除示例文件，创建 main.py：

del hello.py  # Windows
rm hello.py   # macOS/Linux

创建 main.py 文件，写入以下内容：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "Hello, FastAPI with uv!"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

6. 运行项目

6.1 使用 uv run 启动

uv run uvicorn main:app --reload

命令解释：

uv run：在项目虚拟环境中运行命令
uvicorn main:app：启动 main.py 文件中的 app 应用
--reload：开启热重载，代码修改后自动重启

预期输出：

INFO:     Will watch for changes in these directories: ['C:\\Users\\zzy\\Desktop\\fastapi-demo']
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
INFO:     Started server process [67890]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

6.2 测试 API

打开浏览器访问：

根路径：http://127.0.0.1:8000
带参数：http://127.0.0.1:8000/items/42?q=test
API 文档：http://127.0.0.1:8000/docs

预期响应：

{
  "message": "Hello, FastAPI with uv!"
}

6.3 停止服务

在终端按 Ctrl + C 停止服务。

7. 项目依赖管理

7.1 添加开发依赖

安装代码格式化工具（仅开发环境使用）：

uv add --dev ruff pytest

这些依赖会被添加到 pyproject.toml 的 dev-dependencies 组中。

7.2 同步依赖（重要）

当你从 Git 克隆项目、切换分支、或者修改了 pyproject.toml 后，需要同步依赖：

uv sync

uv sync 的作用：

根据 uv.lock 文件安装精确版本的所有依赖
如果 .venv 不存在，会自动创建虚拟环境
确保项目环境与锁定文件完全一致
移除 uv.lock 中不存在但虚拟环境中有的包

使用场景：

克隆项目后首次安装：

git clone https://github.com/user/fastapi-demo.git
cd fastapi-demo
uv sync

团队协作时同步依赖：

git pull
uv sync

手动修改 pyproject.toml 后：

# 编辑 pyproject.toml 添加依赖
uv sync

常用选项：

冻结模式（生产环境推荐）：

uv sync --frozen

不更新 uv.lock，严格按照锁定文件安装，如果不一致会报错。

只安装生产依赖（不含开发依赖）：

uv sync --no-dev

强制重新解析依赖：

uv sync --refresh

uv add vs uv sync 的区别：

命令	作用	使用场景
`uv add`	添加新依赖到 `pyproject.toml` 并安装	主动添加新包
`uv sync`	根据 `uv.lock` 同步所有依赖	克隆项目、切换分支、团队协作

输出示例：

Resolved 15 packages in 234ms
Downloaded 3 packages in 1.2s
Installed 15 packages in 89ms
 + fastapi==0.110.0
 + uvicorn==0.27.0
 + ...

7.3 移除依赖

uv remove 包名

8. 虚拟环境说明

8.1 自动创建

uv 在首次运行 uv add 或 uv run 时会自动创建 .venv 虚拟环境。

8.2 手动激活虚拟环境（可选）

如果需要手动激活环境：

Windows：

.venv\Scripts\activate

macOS/Linux：

source .venv/bin/activate

激活后，终端提示符会显示 (.venv)。

8.3 退出虚拟环境

deactivate

9. 完整项目结构

最终的项目结构如下：

fastapi-demo/
├── .venv/              # 虚拟环境（自动生成）
├── .python-version     # Python 版本固定文件（如果使用了 pin）
├── pyproject.toml      # 项目配置
├── uv.lock             # 依赖锁定文件
├── main.py             # FastAPI 应用
└── README.md           # 项目说明

10. 常见问题

10.1 镜像源配置后仍然很慢

检查配置是否生效：

uv pip install --dry-run requests -v

查看输出中的 index-url 是否为配置的镜像源。

10.2 依赖冲突

如果遇到依赖冲突，可以尝试：

uv lock --upgrade
uv sync

10.3 清理缓存

如果安装出现问题，可以清理缓存后重试：

uv cache clean
uv sync

10.4 切换项目 Python 版本

如果需要更改项目使用的 Python 版本：

# 重新固定版本
uv python pin 3.12

# 重新创建虚拟环境
uv venv --python 3.12

# 重新安装依赖
uv sync

uv-启动项目与配置镜像

uv 启动 Python 项目与配置镜像

1. Python 版本管理

1.1 查看可用的 Python 版本

1.2 查看本地已安装的 Python 版本

1.3 安装指定 Python 版本

1.4 查找 Python 解释器路径

2. 创建 FastAPI 项目

2.1 使用默认 Python 版本初始化

2.2 指定 Python 版本初始化（推荐）

2.3 查看项目配置

2.4 生成的项目结构

2.5 固定项目 Python 版本（可选）

3. 配置镜像源（重要）

2.1 方式一：项目级配置（推荐）

2.2 方式二：全局配置

2.3 方式三：临时使用镜像

4. 安装 FastAPI 依赖

4.1 添加 FastAPI 和 Uvicorn

4.2 查看已安装的依赖

5. 编写 FastAPI 应用

5.1 创建主程序文件

6. 运行项目

6.1 使用 uv run 启动

6.2 测试 API

6.3 停止服务

7. 项目依赖管理

7.1 添加开发依赖

7.2 同步依赖（重要）

7.3 移除依赖

8. 虚拟环境说明

8.1 自动创建

8.2 手动激活虚拟环境（可选）

8.3 退出虚拟环境

9. 完整项目结构

10. 常见问题

10.1 镜像源配置后仍然很慢

10.2 依赖冲突

10.3 清理缓存

10.4 切换项目 Python 版本

评论区