uv init 完整用法（Python 最快包管理器）

在 Python 开发者生态中，由 Astral 团队打造的 uv 绝对是近年来最具统治力的神级工具（使用 Rust 编写，速度比传统的 pip 和 poetry 快数十倍到上百倍）。

在 uv 的最新版本中，uv init 已经演变为一个非常强大的项目初始化命令，它不仅能帮你创建一个干净的 Python 目录，还能瞬间配置好符合现代标准的开发环境（甚至连虚拟环境和 Python 版本都一并搞定）。

以下是 uv init 的完整用法、进阶参数与核心工程实践：

1. 基础用法：一键创建现代 Python 项目

在终端中运行最基本的命令：

Bash

uv init my-project
cd my-project

执行后，uv 会在 my-project 目录下自动生成以下标准结构：

Plaintext

my-project/
├── .python-version # 锁定当前项目使用的 Python 版本（如 3.12）
├── .gitignore      # 预配置好 Python 常见忽略项
├── pyproject.toml  # 现代 Python 核心配置文件（替代 setup.py / requirements.txt）
└── hello.py        # 默认生成的入口示例代码

🚀 极速运行体验：

创建完成后，你甚至不需要手动去激活虚拟环境，直接运行：

Bash

uv run hello.py

uv 会在后台自动、瞬间 创建好虚拟环境（.venv），下载并锁定你在 .python-version 中指定的 Python 释译器，并直接运行代码。

2. uv init 核心参数详解（高级玩家必备）

通过附加参数，你可以直接让 uv init 生成符合你特定工程需求的模板。

① --lib：初始化为一个"可发布的库（Library）"

如果你不仅是写个脚本，而是打算开发一个可以打包发布到 PyPI 的第三方 Python 库：

Bash

uv init my-library --lib

• 变化 ：它不会生成 hello.py，而是会生成标准的 src/my_library/__init__.py 目录结构。同时，pyproject.toml 中会自动配置好构建系统（Build-backend，默认使用轻量且极速的 hatchling）。

② --app：明确初始化为一个"应用/可执行程序"

如果你想开发一个可以通过命令行直接全局运行的 CLI 工具或独立应用：

Bash

uv init my-app --app

• 变化 ：结构与默认类似，但 pyproject.toml 会自动为你配置好对应的脚本入口点（Script Entrypoints）。

③ --python：指定特定的 Python 版本

如果你的生产环境需要严格锁死 Python 版本（例如必须用老版本 3.10 或者抢鲜版 3.13）：

Bash

uv init my-project --python 3.10

• 效果 ：uv 会自动在 .python-version 里写入 3.10。如果你的电脑上没有安装 3.10，当你第一次运行 uv run 或 uv venv 时，uv 会用极快的速度从官方源自动下载一个干净的、免安装的 Python 3.10 解释器隔离供该项目使用。

④ --package：自定义包名

默认情况下，uv init 会将文件夹的名字作为 Python 包的名字。如果你的文件夹名字带空格或横杠（如 my-data-science-project），你可以强制指定合规的包名：

Bash

uv init my-data-science-project --package my_ds_project

3. pyproject.toml 的现代配置解析

使用 uv init 生成的 pyproject.toml 采用了 PEP 621 现代标准，干净且极具扩展性。一个默认生成的配置文件大致如下：

Ini, TOML

[project]
name = "my-project"
version = "0.1.0"
description = "Add a short description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [] # 后面使用 uv add 导入的依赖会自动死死锁在这里

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

4. uv init 之后的标准工作流（教科书级日常）

当你用 uv init 啪一下把项目骨架搭好后，接下来的标配连招是：

第一步：添加依赖（如大模型开发常用库）

Bash

uv add langchain langchain-core pydantic

• 硬核体验 ：你会体验到什么叫"瞬移"。传统 pip install 需要花几十秒甚至几分钟去解析依赖冲突、下载轮子；而 uv 的解析和缓存机制能让这些库在 1 秒钟内安装并锁定完毕，同时自动更新 pyproject.toml。

第二步：添加只在开发/测试时使用的库

Bash

uv add --dev pytest black ruff

• 效果 ：这些库会被归类到 pyproject.toml 的 [dependency-groups] 里的 dev 分组中，确保生产环境部署时不会带上这些冗余的测试工具。

第三步：一键运行或测试

Bash

uv run pytest

💡 总结与避坑

1. 别再手动 virtualenv .venv 了 ：以前用 pip，我们习惯了进项目先敲命令建虚拟环境再 source .venv/bin/activate。用 uv 之后，你可以彻底忘掉激活环境这件事 。uv init 配合 uv run 会在后台全自动帮你打理好虚拟环境的生老病死。

2. 完美平替 Poetry/Pipenv ：如果你正在痛苦于 Poetry 缓慢的依赖解析（Locking 过程），赶紧找个空文件夹体验一下 uv init， Rust 带来的全方位速度碾压会让你再也回不去。