uv 项目工作流指南：从 uv init 创建项目到依赖管理与构建分发

uv 项目工作流指南从 uv init 创建项目到依赖管理与构建分发【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv本文以 uv 官方项目指南docs/guides/projects.md为主体系统讲解如何使用 uv 创建并管理一个 Python 项目从uv init初始化、理解项目结构pyproject.toml、.venv、uv.lock、依赖的增删与升级到运行命令与构建可分发产物。读完本文你可以独立完成一个 uv 项目的初始化、依赖治理、版本管理与构建打包全流程并结合 uv 仓库源码理解每个命令背后的实现机制。一、创建新项目uv 支持管理以pyproject.toml定义依赖的 Python 项目。创建新项目使用uv init命令$ uv init hello-world $ cd hello-world也可以在已有目录中就地初始化$ mkdir hello-world $ cd hello-world $ uv init执行后 uv 会创建如下文件与目录├── .git/ ├── .gitignore ├── .python-version ├── pyproject.toml ├── README.md └── src └── hello_world └── __init__.py生成的pyproject.toml定义了一个名为hello-world的入口点指向__init__.py中一个简单的 Hello world 程序。可以直接用uv run尝试运行$ uv run hello-world Hello from hello-world!源码视角uv init做了什么uv init的实现入口是 init 函数crates/uv/src/commands/project/init.rs。从源码结构看有几个值得注意的行为拒绝重复初始化若目标目录已存在pyproject.toml命令会直接报错Project is already initialized见 init.rs 第 106-113 行。项目名默认取自目录名当未显式提供包名时uv 会取目录名并做规范化——去除首尾空白、把内部空白替换为连字符再按 Python 包名规则校验不合法时会提示使用--name显式指定见 init.rs 第 116-147 行。按需创建 README在初始化完成后若 README.md 尚不存在则自动创建空文件见 init.rs 第 173-179 行。参数面很宽从函数签名init.rs 第 45-67 行可以看到该命令还支持脚本模式InitKind::Script、--bare仅最小文件集、--python、--build-backend、--vcs、--author-from、--pin-python、--no-workspace等选项覆盖脚本初始化与项目初始化两种形态。二、项目结构详解一个 uv 项目由几个协同工作的重要组成部分构成。除了uv init创建的文件外uv 还会在你第一次执行项目命令即uv run、uv sync或uv lock时在项目根目录创建虚拟环境.venv和锁文件uv.lock。完整的项目结构如下. ├── .git/ ├── .venv/ │ ├── bin │ ├── lib │ └── pyvenv.cfg ├── .gitignore ├── .python-version ├── README.md ├── src │ └── hello_world │ └── __init__.py ├── pyproject.toml └── uv.lock下面逐一解读各文件的职责。2.1pyproject.toml项目元数据的中心pyproject.toml包含项目的元数据。uv init生成的典型内容如下[project] name hello-world version 0.1.0 description Add your description here readme README.md authors [ { name ferris, email ferrisexample.org } ] requires-python 3.14 dependencies [] [project.scripts] hello-world hello_world:main [build-system] requires [uv_build0.12.9,0.13] build-backend uv_build这个文件是你声明依赖、以及描述项目说明、许可证等信息的地方。你可以手工编辑它也可以使用uv add、uv remove等命令在终端中管理项目。关于pyproject.toml格式本身的更完整规范PEP 621 及后续标准可参考 Python 打包官方指南。除项目元数据外pyproject.toml还用来承载 uv 自身的配置项写在[tool.uv]小节中详见 配置文件说明。2.2.python-version锁定默认 Python 版本.python-version文件保存项目默认的 Python 版本。它告诉 uv 在创建项目虚拟环境时应使用哪个 Python 解释器从而保证团队在不同机器上获得一致的运行时版本。2.3.venv项目虚拟环境.venv目录包含项目的虚拟环境——一个与系统其余部分隔离的 Python 环境uv 会把项目依赖安装到这里。结合 项目布局文档可以补充几点实用细节.venv默认存放在pyproject.toml旁边目的是让编辑器能直接发现它从而提供代码补全与类型提示不建议将.venv纳入版本控制uv 内部会为其写入.gitignore实现自动排除不建议手工修改项目环境例如uv pip install项目依赖请用uv add一次性依赖请用uv run --with。2.4uv.lock跨平台锁文件uv.lock是一个跨平台universal锁文件包含项目依赖的精确版本信息。与用于声明宽泛需求的pyproject.toml不同锁文件记录的是被安装到项目环境中的精确解析版本。它应当被提交到版本控制系统以实现跨机器的一致、可复现安装。uv.lock是人類可读的 TOML 文件但由 uv 管理、不应手工编辑。更深入的说明包括它与 PEP 751 标准格式pylock.toml的关系见 锁文件文档。三、依赖管理3.1 添加依赖uv add使用uv add将依赖写入pyproject.toml同时更新锁文件与项目环境$ uv add requests也可以指定版本约束或替代来源$ # 指定版本约束 $ uv add requests2.31.0 $ # 添加 git 依赖 $ uv add githttps://github.com/psf/requests如果你正从requirements.txt迁移可以使用-r标志把文件中的全部依赖一次性加入项目并可同时用-c提供约束文件$ # 添加 requirements.txt 中的所有依赖 $ uv add -r requirements.txt -c constraints.txt3.2 移除依赖uv remove$ uv remove requests3.3 升级单个包uv lock --upgrade-package$ uv lock --upgrade-package requests--upgrade-package标志会尝试将指定包更新到最新的兼容版本同时保持锁文件其余部分不变——这是做选择性升级的关键手段避免一次uv lock全量重解析带来的版本漂移。更多依赖管理细节依赖组、extras、来源类型等见 依赖管理文档。四、查看项目版本uv versionuv version用于读取或更新项目的包版本。获取包版本$ uv version hello-world 0.7.0只输出版本号省略包名使用--short$ uv version --short 0.7.0以 JSON 格式输出使用--output-format json$ uv version --output-format json { package_name: hello-world, version: 0.7.0, commit_info: null }源码视角uv version的读写双模式uv version的实现位于 project_version 函数crates/uv/src/commands/project/version.rs。从源码结构看只读快速路径当既没有传入具体版本号、也没有--bump时命令被判定为纯读取is_read_only见 version.rs 第 118-138 行配合--frozen还可以跳过解析直接读锁文件中的版本。写路径会联动锁与同步更新版本号后命令会调用 lock_and_sync 重新执行 lock 与 sync保证环境与新版本一致--dry-run则只做预览不落盘见 version.rs 第 331-333 行。防误用提示在非项目目录执行uv version找不到pyproject.toml时uv 会提示如果你想查看 uv 自身版本请使用uv self version见 version.rs 第 392-400 行。关于如何在发布时更新版本号的完整建议包括--bump major/minor/patch/alpha/beta/rc/dev/post/stable的用法与组合约束见 打包指南的版本更新章节。五、运行命令uv run与uv syncuv run可以在项目环境中运行任意脚本或命令。每次调用uv run之前uv 都会校验锁文件与pyproject.toml保持一致、项目环境与锁文件保持一致从而无需人工干预即可保持项目同步。uv run保证你的命令运行在一个所有依赖都处于锁定版本的环境中。注意默认情况下uv run不会移除环境中的多余包不在锁文件中的包。处理方式详见 多余包处理说明。示例一使用依赖中的 CLI 工具。先添加flask再运行其命令行$ uv add flask $ uv run -- flask run -p 3000示例二运行脚本。假设有如下脚本example.py# 依赖项目依赖 import flask print(hello world)$ uv run example.py替代方案手动同步并激活环境。你也可以用uv sync手动更新环境然后激活虚拟环境再执行命令。macOS 和 Linux$ uv sync $ source .venv/bin/activate $ flask run -p 3000 $ python example.pyWindowsPS uv sync PS .venv\Scripts\activate PS flask run -p 3000 PS python example.py注意如果不使用uv run必须在虚拟环境处于激活状态下才能运行项目中的脚本和命令。虚拟环境的激活方式因 shell 和平台而异。更多在项目内运行命令与脚本的细节见 运行命令文档。六、构建分发产物uv builduv build用于为项目构建源分发包sdist与二进制分发包wheel。默认情况下uv build构建当前目录中的项目并把产物放入dist/子目录$ uv build $ ls dist/ hello_world-0.1.0-py3-none-any.whl hello_world-0.1.0.tar.gz构建完成后dist/下会同时得到 wheel 和 sdist 两类产物可直接用于uv publish发布或分发到其他索引。更完整的构建参数目标类型选择、输出目录等见 构建项目文档。七、延伸阅读项目模型全景布局、锁定与同步、workspace 等项目概念索引各命令的完整参数参考CLI 参考将uv.lock导出为requirements.txt、pylock.toml等其他格式导出锁文件打包与发布流程版本号更新、发布到索引打包指南【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考