Python uv 完整使用教程

一、uv 是什么

uv 是 Astral 团队用 Rust 开发的一体化 Python 工具，单文件二进制 ，一套命令替代：pip + venv/virtualenv + pyenv + pip-tools + ruff，核心优势：

1. 1. 极速：依赖安装比 pip 快10~100倍，并行下载+全局缓存；
2. 2. 一站式：管理 Python 版本、虚拟环境、包依赖、代码格式化、锁文件；
3. 3. 轻量化：虚拟环境复用缓存，磁盘占用极小；
4. 4. 完全兼容 ：支持 requirements.txt、pyproject.toml，无缝迁移旧项目。

uv vs pip vs conda 简单区分

工具	定位	适用场景
uv	Python全栈包/环境管理器，只处理PyPI包	Web后端、脚本、AI纯Python项目（FastAPI/LangChain）
pip	官方纯Python包管理器，无环境/版本管理	老旧简易脚本
conda	跨语言管理器，支持CUDA/C++底层库	深度学习、需要GPU编译库的项目

二、uv 安装

Windows（PowerShell管理员）

irm https://astral.sh/uv/install.ps1 | iex

Mac / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

备选（已有Python，不推荐主力）

pip install uv

验证安装

新开终端执行

uv --version
uv help

三、核心功能完整实操（分5大模块）

模块1：Python版本管理（替代pyenv）

# 查看本地已装Python版本
uv python list
# 查看所有可下载官方Python
uv python list --all

# 自动下载安装指定Python版本
uv python install 3.11
uv python install 3.12.4

# 项目绑定指定Python（自动创建.python-version文件）
uv python pin 3.11

模块2：虚拟环境管理（替代venv）

1. 创建虚拟环境

# 默认创建 .venv 目录，使用系统默认Python
uv venv

# 指定Python版本创建环境
uv venv .venv311 --python 3.11

# 指定环境目录名
uv venv langchain_env

2. 激活环境

• • Windows CMD/PowerShell

  cmd

  langchain_env\Scripts\activate.bat

  powershell

  .\langchain_env\Scripts\Activate.ps1

• • Mac/Linux

  source langchain_env/bin/activate

3. 环境辅助命令

# 查看当前环境信息
uv venv info
# 删除虚拟环境
uv venv rm .venv

模块3：两种项目工作流（新项目标准流 / 老项目兼容pip流）

工作流A：标准uv项目（推荐，pyproject.toml 管理依赖）

1. 初始化新项目

# 创建项目，自动生成 pyproject.toml、uv.lock、.gitignore
uv init fastapi_demo
cd fastapi_demo

# 初始化同时指定Python版本
uv init -p 3.11 fastapi_demo

2. 添加/卸载/更新依赖

# 安装运行依赖（写入pyproject.toml）
uv add fastapi uvicorn pydantic

# 安装开发依赖（测试、格式化工具）
uv add --dev pytest ruff

# 安装指定版本
uv add requests==2.31.0

# 卸载包
uv remove uvicorn

# 更新单个包到最新
uv upgrade pydantic
# 更新所有依赖
uv upgrade --all

3. 同步环境（多人协作核心）

uv.lock 精确锁定所有依赖版本，团队统一环境

# 根据pyproject.toml + uv.lock 同步虚拟环境
uv sync
# 只同步生产依赖，跳过dev
uv sync --no-dev

4. 运行脚本/项目（自动使用虚拟环境，无需手动激活）

# 直接运行py文件，自动加载.venv依赖
uv run main.py

# 运行uvicorn启动FastAPI
uv run uvicorn main:app --reload

# 运行测试
uv run pytest

工作流B：兼容旧项目（沿用 requirements.txt，uv pip 语法）

完全复用pip习惯，只把pip替换为uv pip

# 创建虚拟环境
uv venv
# 安装依赖文件
uv pip install -r requirements.txt

# 冻结当前环境输出requirements.txt
uv pip freeze > requirements.txt

# 安装单个包
uv pip install sqlalchemy aiomysql
# 卸载
uv pip uninstall sqlalchemy

模块4：镜像源配置（国内加速，必配）

1. 设置全局清华PyPI镜像

uv config set registry.index-url https://pypi.tuna.tsinghua.edu.cn/simple

2. 查看当前配置

uv config list

模块5：常用辅助命令

# 打印依赖树，查看包之间层级关系
uv tree

# 导出锁文件为requirements.txt（给pip/conda兼容）
uv export --format requirements-txt > requirements.txt

# 代码格式化、静态检查（内置ruff）
uv format
uv check

四、实战完整流程示例（FastAPI后端项目）

1. 1. 初始化项目并指定Python3.11

   uv init -p 3.11 fastapi_mysql
   cd fastapi_mysql

2. 2. 安装业务依赖

   uv add fastapi uvicorn pydantic sqlalchemy aiomysql redis
   uv add --dev pytest ruff

3. 3. 编写main.py，直接运行

   uv run uvicorn main:app --host 0.0.0.0 --port 8000

4. 4. 团队协作：其他人拉取代码后一键复现环境

   uv sync
   uv run uvicorn main:app

五、高频使用问题

1. 不需要手动激活 .venv 吗？

不需要。uv run xxx 会自动读取项目下的.venv ，自动使用该环境的Python与包，省去手动activate。

2. uv 和 conda 怎么配合？

• • 纯Python项目优先uv，速度更快、体积小；
• • 涉及CUDA、PyTorch、MKL等底层C库时，用conda创建基础环境，在conda环境内使用uv管理Python包；
• • 互相迁移：uv pip freeze > requirements.txt 导出给conda使用。

3. PyCharm如何配置uv虚拟环境？

1. 1. File → Settings → Project → Python Interpreter
2. 2. Add → Existing Environment，选择项目目录下 .venv/Scripts/python.exe（Windows）/ .venv/bin/python（Mac/Linux）
3. 3. 确认后，编辑器、运行、终端自动使用uv创建的环境。

4. uv lock 文件作用？

记录所有依赖精确版本+子依赖版本 ，保证所有开发者、服务器安装的包版本完全一致，解决"本地能跑线上崩"。禁止手动编辑uv.lock。