管理项目

创建新项目

# 使用 uv 创建一个新的 Python 项目
uv init example

# 或者，在工作目录中初始化一个项目
mkdir example && cd example && uv init

管理依赖

使用 uv add 命令将依赖添加到 pyproject.toml 中，这也将更新锁文件和项目环境。

uv add request

# 指定版本约束
uv add 'request=2.31.0'

# 添加一个 git 依赖，（备用源）
uv add git+https://github.com/psf/request

如果你正在从 requirements.txt 文件迁移，你可以使用 -r 标志来添加文件中的所有依赖项：

# 从 `requirements.txt` 添加所有依赖项。
uv add -r requirements.txt -c constraints.txt

移除一个包，使用 uv remove

uv remove request

升级一个包，使用带有 –upgrade-package 标志的 uv lock：

uv lock --upgrade-package request

--upgrade-package 标志将尝试将指定的包更新到最新的兼容版本，同时保持锁文件的其余部分不变。

运行命令

uv run 可用于在项目环境中运行任意脚本或命令。

uv add flask
uv run -- flask run -p 3000

或者，运行一个 Python 程序

uv run example.py

或者，使用 uv sync 手动更新环境，然后在执行命令激活它。

uv sync
source .venv/bin/activate
flask run -p 3000
python example.py

虚拟环境必须处于激活状态，才能在没有 uv run 的情况下在项目中运行脚本和命令。

构建分发包

要将你的项目分发给其他人（例如，上传到像 PyPI 这样的索引），你需要将其构建成可分发的格式。

Python 项目通常以源码分发包（sdist）和二进制分发包（wheel）两种形式分发。前者通常是一个包含项目源代码和一些附加元数据的 .tar.gz 或 .zip 文件，而后者是一个包含可直接安装的预构建构件的 .whl 文件。

uv build 用于为你的项目构建源代码分发包和二进制分发包。

默认情况下，uv build 将在当前目录中构建项目。并将构建的工件刚在 dist/ 子目录中。通过向 uv build 提供路径来在不同目录中构建项目。例如 uv build path/to/project。

uv build 将首先构建一个源码分发包，然后从该源码分发包构建一个二进制分发包（wheel）。

使用 uv build –sdist 将 uv build 限制为仅构建源码分发包，使用 uv build –wheel 仅构建二进制分发包，或使用 uv build --sdist --wheel 从源码构建两种分发包。