【Python】uv基础使用

// 前提是不用conda - 因为uv有自己的虚拟环境

uv介绍

1.介绍

uv是一款Python的包管理、虚拟环境管理的工具；由Rust编写，所以非常快 - 安装包快、删除快...相对于pip管理而言，命令简洁易学。

应用迁移时简单，包的版本管理简单。

和其他工具对比如下：

2.配置文件pyproject.toml和uv.lock锁文件

1️⃣pyproject.toml

这个文件类似于SpringBoot中的application.yaml + pom.xml 的组合，负责项目的基础配置 + 宽松的依赖说明；如下：

toml 复制代码

# pyproject.toml - Python 项目配置文件

[build-system]
requires = ["hatchling>=1.0.0"]
build-backend = "hatchling.build"

[project]
name = "my-awesome-project"
version = "0.1.0"
description = "一个很棒的项目"
readme = "README.md"
requires-python = ">=3.11"
license = { text = "MIT" }
authors = [
    { name = "张三", email = "zhangsan@example.com" }
]

# 生产依赖
dependencies = [
    "fastapi>=0.100.0",
    "uvicorn>=0.23.0",
    "sqlalchemy>=2.0.0",
]

# 可选依赖组
[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "black>=23.0.0",
    "ruff>=0.0.280",
]
docs = [
    "mkdocs>=1.5.0",
    "mkdocs-material>=9.0.0",
]

# 项目脚本入口点
[project.scripts]
my-app = "my_package.cli:main"

# uv 特定配置
[tool.uv]
dev-dependencies = [
    "pytest-cov>=4.1.0",
]

# 工具配置示例
[tool.black]
line-length = 100
target-version = ['py311']

[tool.ruff]
line-length = 100
select = ["E", "F", "I", "N"]

uv管理包的时候，你使用uv add添加了一个包，会自动写入pyproject.toml文件-包名和版本号；

2️⃣uv.lock

uv.lock 是锁定文件 ，记录了所有依赖的确切版本 和依赖树结构。如下：

bash 复制代码

# uv.lock - 锁定所有依赖的确切版本

version = 1
requires-python = ">=3.11"

[[package]]
name = "requests"
version = "2.31.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "certifi" },
    { name = "charset-normalizer" },
    { name = "idna" },
    { name = "urllib3" },
]
sdist = { url = "https://files.pythonhosted.org/packages/.../requests-2.31.0.tar.gz", hash = "sha256:..." }
wheels = [
    { url = "https://files.pythonhosted.org/packages/.../requests-2.31.0-py3-none-any.whl", hash = "sha256:..." }
]

[[package]]
name = "certifi"
version = "2024.2.2"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/.../certifi-2024.2.2.tar.gz", hash = "sha256:..." }
wheels = [
    { url = "https://files.pythonhosted.org/packages/.../certifi-2024.2.2-py3-none-any.whl", hash = "sha256:..." }
]

[[package]]
name = "urllib3"
version = "2.2.1"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/.../urllib3-2.2.1.tar.gz", hash = "sha256:..." }

3️⃣是否提交到git

++两个文件都必须提交到git++；

第一份pyproject.toml是给人看的文件；而uv.lock是给机器看的，负责梳理包的依赖关系的文件。只有同时拥有这两份配置文件，就像你之前必须有requirements.txt才能根据这个配置文件安装包从而搭建项目环境。

而一个新的项目 - 利用uv管理，搭建环境十分简单；假设使用docker进行部署，那么Dockerfile应该这么写：

python 复制代码

# Dockerfile - 使用国内镜像源加速

FROM python:3.11-slim

# 安装 uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# 设置 pip 镜像源（uv 也会使用）
RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 或者通过环境变量设置 uv 镜像源
ENV UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

WORKDIR /app

# 复制依赖文件
COPY pyproject.toml uv.lock ./
COPY src ./src

# 安装依赖 - 核心
RUN uv sync --frozen --no-dev

ENV PATH="/app/.venv/bin:$PATH"

CMD ["python", "-m", "src.main"]

uv常用命令

1.项目初始化uv init

bash 复制代码

# 创建新项目
uv init

# 在指定目录创建项目
uv init my-project

# 创建带 pyproject.toml 的项目
uv init --app

# 创建库项目（适合打包发布）
uv init --lib

2.虚拟环境管理uv venv

bash 复制代码

# 创建虚拟环境（默认在当前目录创建 .venv）
uv venv

# 指定 Python 版本创建
uv venv --python 3.11
uv venv --python 3.12

# 指定虚拟环境路径
uv venv /path/to/venv

# 创建系统级 Python 链接的虚拟环境
uv venv --system-site-packages

3.激活/退出虚拟环境

bash 复制代码

# Windows
.\.venv\Scripts\activate

# 退出虚拟环境
deactivate

4.包管理

同步包 - uv sync // 安装 pyproject.toml 中的所有依赖

bash 复制代码

# 安装 pyproject.toml 中的所有依赖
uv sync

添加包 - uv add

bash 复制代码

# 添加单个包
uv add requests

# 添加多个包
uv add requests pandas numpy

# 指定版本添加
uv add "requests>=2.28.0,<3.0.0"
uv add "pandas==2.0.3"

删除包 - uv remove

bash 复制代码

# 移除包
uv remove requests

# 移除多个包
uv remove requests pandas

更新包 - uv add --upgrade / uv sync --upgrade

bash 复制代码

# 更新所有包
uv sync --upgrade

# 更新指定包
uv add --upgrade requests

# 更新包到最新版本（保持兼容性）
uv add --upgrade-package requests

# 查看可更新的包
uv tree --outdated

查看已安装的包列表 uv tree / uv pip list / uv pip show 包

bash 复制代码

# 列出所有包
uv pip list

# 查看包的详细信息
uv pip show requests

# 树形显示依赖关系
uv tree

# 显示依赖深度
uv tree --depth 2

5.运行命令 - uv run 脚本

bash 复制代码

# 在虚拟环境中运行脚本
uv run python script.py

uv run pytest

uv run where python  # Windows

6.虚拟环境中的python管理 - uv python

python 复制代码

# 查看可用的 Python 版本
uv python list

# 下载特定 Python 版本
uv python install 3.11
uv python install 3.12.2

# 查看当前使用的 Python 版本
uv python find

# 设置项目使用的 Python 版本
uv python pin 3.11

7.配置uv镜像源

bash 复制代码

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

8.其他 - 删除.venv

bash 复制代码

# 删除重建虚拟环境
rmdir /s .venv  # Windows
uv venv
uv sync

安装uv并使用uv创建虚拟环境

1.安装uv

pip install uv

2.初始化

uv init

3.创建uv 环境

uv venv

// 可以修改命令，指定venv中的python版本；

4.激活环境

..venv\Scripts\activate

5.使用uv管理

uv add openai python-dotenv

Pycharm环境下使用uv配置Python解释器

1.前提条件

Pycharm版本必须在2024.3.2+，我们使用2025版本的Pycharm就ok；
电脑中安装了uv.exe；

2.uv创建的venv中内置了Python，我们需要用uv管理项目 -> 设置venv中的解释器为项目的解释器；这也意味着项目会使用这个python.exe所在的.venv作为识别的包，这个里面的第三方库将会作为Pycharm识别项目的环境。

3.配置Python解释器