UV Python 包和项目管理工具

UV 概述

• 官方文档：https://uv.doczh.com/pip/compile/
• Github：https://github.com/astral-sh/uv

uv 为 Python 开发提供核心功能——从安装 Python 和编写简单脚本，到支持多 Python 版本和多平台的大型项目开发。特点如下：

• 🚀替代pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv等的单一工具。
• ⚡️比pip快10-100倍。
• 🗂️提供全面的项目管理，具有通用的lockfile。
• ❇️运行脚本，支持内联依赖元数据。
• 🐍安装和管理Python版本。
• 🛠️运行和安装作为Python包发布的工具。
• 🔩包含一个pip兼容的接口，用于使用熟悉的CLI提高性能。

An extremely fast Python package manager.
Usage: uv [OPTIONS] <COMMAND>
Commands:run      Run a command or scriptinit     Create a new projectadd      Add dependencies to the projectremove   Remove dependencies from the projectversion  Read or update the project's versionsync     Update the project's environmentlock     Update the project's lockfileexport   Export the project's lockfile to an alternate formattree     Display the project's dependency treetool     Run and install commands provided by Python packagespython   Manage Python versions and installationspip      Manage Python packages with a pip-compatible interfacevenv     Create a virtual environmentbuild    Build Python packages into source distributions and wheelspublish  Upload distributions to an indexcache    Manage uv's cacheself     Manage the uv executablehelp     Display documentation for a commandCache options:-n, --no-cache               Avoid reading from or writing to the cache, instead using a temporary directory for theduration of the operation [env: UV_NO_CACHE=]--cache-dir <CACHE_DIR>  Path to the cache directory [env: UV_CACHE_DIR=]Python options:--managed-python       Require use of uv-managed Python versions [env: UV_MANAGED_PYTHON=]--no-managed-python    Disable use of uv-managed Python versions [env: UV_NO_MANAGED_PYTHON=]--no-python-downloads  Disable automatic downloads of Python. [env: "UV_PYTHON_DOWNLOADS=never"]Use `uv help` for more details.

安装UV

Mac or Linux

curl -LsSf https://astral.sh/uv/install.sh | sh
wget -qO- https://astral.sh/uv/install.sh | sh
# 安装特定的版本
curl -LsSf https://astral.sh/uv/0.7.4/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
#安装特定的版本
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.7.4/install.ps1 | iex"

通过PyPI安装

pipx install uv
pip install uv

升级UV

uv self update
pip install --upgrade uv

环境管理

uv 支持创建虚拟环境 ，uv 默认要求使用虚拟环境。一般在项目的目录下使用uv venv .venv 创建虚拟环境

# 创建虚拟环境
uv venv
# 在 my-name 目录下创建一个虚拟环境
uv venv my-name
# 使用 Python 3.11 创建一个虚拟环境
uv venv --python 3.11
# 激活虚拟环境 创建的特定的虚拟环境
source my-name/bin/activate
# 退出虚拟环境的激活
source my-name/bin/deactivate

项目管理

Python 项目元数据在pyproject.toml文件中定义。uv 需要此文件来识别项目的根目录

[project]
name = "python-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["pandas>=2.3.3","requests>=2.32.5",
]

调用 uv run 时，如果项目环境尚不存在，它将创建该环境；如果已存在，则确保其为最新状态。也可以使用 uv sync 显式创建项目环境

锁定文件

uv 会在 pyproject.toml 旁边创建一个 uv.lock 文件，uv.lock 是一个通用或跨平台的锁定文件，它记录了在所有可能的 Python 标识（如操作系统、架构和 Python 版本）下要安装的软件包，uv.lock 是一个人类可读的 TOML 文件，但由 uv 管理，不应手动编辑。uv.lock 格式特定于 uv，其他工具无法使用。

在使用项目环境的 uv 调用（即 uv sync 和 uv run）过程中，锁定文件会自动创建和更新。也可以使用 uv lock 显式更新锁定文件。

创建项目

# 使用uv 初始化一个 项目 项目名称为：example-app
uv init example-app
# 查看初始化项目的结构
$ tree example-appexample-app
|-.python-version
|-.venv
|-main.py
|-pyproject.toml
|-README.md
|-uv.lock

pyproject.toml 包含基本元数据。它不包含构建系统，它不是一个 包，也不会安装到环境中

[project]
name = "python-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["pandas>=2.3.3","requests>=2.32.5",
]

可以使用 uv run 执行 Python 文件

uv run main.py

创建一个打包的应用程序

uv init --package example-pkg
# 源代码会被移动到一个 src 目录中，该目录包含一个模块目录和一个 __init__.p# 会定义一个构建系统，这样项目就会被安装到环境中：[project]
name = "example-pkg"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [][project.scripts]
example-pkg = "example_pkg:main"[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

依赖管理

# 添加依赖项
uv add httpx
uv add "httpx>=0.20"
# 可以使用 --dev、--group 或 --optional 标志将依赖项添加到其他字段# 可以使用 -r 选项将 requirements.txt 文件中声明的依赖项添加到项目中
uv add -r requirements.txt# 删除依赖项
uv remove httpx#特定平台的依赖项
uv add "jax; sys_platform == 'linux'"
# 生成的 pyproject.toml 将在依赖项定义中包含环境标记
dependencies = ["jax; sys_platform == 'linux'"]

镜像源

# 临时环境变量（单次生效）
# 使用阿里云镜像源
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
uv pip install [包名]
# 或清华大学镜像源
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple/# 永久配置（推荐） 在用户目录下创建 uv.toml 文件
[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true
# 或使用清华源
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"# 命令行指定源
uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ [包名]#常用镜像源地址
- https://mirrors.aliyun.com/pypi/simple/
- https://pypi.tuna.tsinghua.edu.cn/simple/
- https://pypi.doubanio.com/simple/
- https://repo.huaweicloud.com/repository/pypi/simple/

锁定与同步

锁定是指将项目的依赖项解析到锁定文件中的过程。同步是指从锁定文件中将部分软件包安装到项目环境中的过程。

在 uv 中，锁定与同步是自动进行的。例如，使用 uv run 时，在调用请求的命令之前，会先对项目进行锁定和同步。这确保了项目环境始终是最新的。同样，像 uv tree 这类读取锁定文件的命令，在运行之前也会自动更新锁定文件。

# 使用锁定文件而不检查其是否为最新，可以使用 --frozen 选项
uv run --frozen main.py# 要运行命令而不检查环境是否为最新，可以使用 --no-sync 选项
uv run --no-sync# 通过在 uv lock 命令中传递 --check 标志来检查锁文件是否为最新版本
uv lock --check# 锁文件会 自动创建，但也可以使用 uv lock 显式创建或更新锁文件
uv lock# 虽然环境会 自动同步，但也可以使用 uv sync 显式同步
uv sync# 导出依赖 requirements-txt
uv export --format requirements-txt

配置文件

uv 支持项目级和用户级的持久化配置文件，具体来说，uv 会在当前目录或最近的父目录中查找 pyproject.toml 或 uv.toml 文件

.evn：uv run 可以从 dotenv 文件（例如 .env、.env.local、.env.development）加载环境变量，要从特定位置加载 .env 文件，可以设置 UV_ENV_FILE 环境变量，或者将 --env-file 标志传递给 uv run

echo "MY_VAR='Hello, world!'" > .env
uv run --env-file .env -- python -c 'import os; print(os.getenv("MY_VAR"))'

检查环境

# 列出环境中的所有包
uv pip list
# 以 JSON 格式列出包
uv pip list --format json
# 以 requirements.txt 格式列出环境中的所有包
uv pip freeze# 要显示已安装包
uv pip show numpy# 要检查环境中是否存在冲突或缺失的依赖项
uv pip check# 同步环境：可以使用 uv pip install 直接从依赖定义文件或编译后的 requirements.txt 文件安装依赖项
uv pip sync requirements.txt
uv pip sync pyproject.toml

锁定依赖

uv 允许以 requirements.txt 格式锁定依赖项。建议使用标准的 pyproject.toml 来定义依赖项，但也支持其他依赖格式

要锁定 pyproject.toml 中声明的依赖项。uv pip compile 的输出仅显示，需要使用 --output-file / -o 参数将其写入文件

uv pip compile pyproject.toml -o requirements.txt

要升级某个依赖项，可使用 --upgrade-package 标志

uv pip compile - -o requirements.txt --upgrade-package ruff