我准备用 uv 初始化一个 python 项目
我用的是苹果笔记本 MacBookPro ，具体的操作系统及硬件参数如下：
uv 是一个使用 Rust 编写的工具，可以用来替代 pip、pipenv、pipx、poetry、virtualenv 等工具的使用，甚至还可以用来管理系统中所安装的 Python 发行版。uv 借鉴了很多现代语言中对于项目依赖的管理方式，项目中对于依赖的管理要远远优于使用 pip 和requirements.txt的方式。
我之前用过 pip 、pipx 等工具，发现 uv 确实要快不少。具体有多快呢？ github 上有个图：
速度比传统 pip 快 10-100倍。
根据官网的介绍，uv 主要支持以下功能：
uv 对多 python 版本和环境的管理很不错，这样你就可以一个项目指定一个特定的 Python 版本，放心使用，想怎么折腾怎么折腾，不会影响全局。
最近比较火的 MCP 很多也是用 uv 运行的，因为用 uv 命令可以直接运行 python 脚本。
uv 的安装非常简单：
# macOS和Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
首先用 uv 管理一下我们本机安装的 Python 环境。即到底安装了几个、哪些版本的 python。
可以用 uv python list 查看，像这样：
可以看到我已经安装了多个版本的 python。 在后面建项目的时候，我选用 3.13 这个版本。当然你也可以根据你的情况下载新的需要使用的版本。这里给出一组相关命令：
uv python install，安装指定版本的 Python。
uv python list，列出系统中当前已经安装的 Python 版本。
uv python find，查找一个已经安装的 Python 版本。
uv python pin，固定当前项目使用指定的 Python 版本。
uv python uninstall，卸载指定版本的 Python。
比如我要安装 3.12 这个版本，我就可以这样：
装好了不想要了，就可以这样卸载掉它：
python 的环境有了以后，我们就可以新建项目了，建项目的时候也要用 uv 来进行初始化。
uv 的项目管理功能更多的借鉴了 Rust 中 Cargo 工具的项目管理理念。但主要区别是 uv 是通过项目目录中的pyproject.toml文件来完成项目管理的。
初始化后会生成以下几个文件 ：
虽然 uv init myproject 会帮你创建项目目录和 pyproject.toml，但默认 不会自动创建虚拟环境（env），所以我们需要手动创建。
# 手动创建虚拟环境
uv venv --python 3.13
# 激活虚拟环境
source .venv/bin/activate
虚拟环境激活后，项目中会多一个.venv 文件夹。
接下来我们要自己创建一下源码目录和测试目录：
到这里工程的相关目录我们就先到此为止，基本上创建完了，然后我们来编辑
pyproject.toml 配置文件。
我们先介绍一下 toml 文件，可能有些朋友不怎么了解它，比如搞 java 开发的。
TOML（Tom's Obvious, Minimal Language）是一种配置文件格式，设计目标是易读、易写、易于解析，非常适合作为程序的配置语言，尤其是在现代的跨平台开发中被广泛采用。
你看这名字是不是觉得肯定跟 Tom 大哥有关系？
对，因为 TOML 由 GitHub 联合创始人 Tom Preston-Werner 在 2013 年发起，用以替代 JSON、INI 等配置格式在可读性和灵活性上的不足。
不过吧，后来这大哥（和她媳妇）不在 GitHub 干了，因为他们的一些不光彩的行为。具体是什么就不多说了，想八卦一下的可以去查查。
toml 配置文件用途广泛，常用于以下场景：
举个例子吧：
# 数据库配置
[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]
enabled = true
# 应用信息
[app]
name = "MyApp"
version = "1.0.0"
release_date = 2025-04-25T12:00:00Z
TOML 的特点可以总结为：
“比 JSON 更适合人读，比 YAML 更适合程序解析。”
它已经成为现代软件开发中最流行的配置文件格式之一，特别是在需要 清晰结构 + 丰富类型 + 可维护性 的场景中表现出色。
常见语言的支持情况：
常见用途：
TOML 与其他格式的对比：
| 特性 | TOML | JSON | YAML | INI |
|---|---|---|---|---|
| 可读性 | ✅ 高 | 中 | 中高（但复杂） | 中 |
| 注释支持 | ✅ 支持 | ❌ 不支持 | ✅ 支持 | ✅ 支持 |
| 数据类型支持 | ✅ 多 | ✅ 多 | ✅ 多 | ❌ 有限 |
| 库支持 | ✅ 常见语言皆支持 | ✅ 全面 | ✅ 全面 | ✅ 较好 |
| 学习曲线 | ✅ 低 | ✅ 低 | ❌ 偏高 | ✅ 极低 |
你看，TOML 作为配置文件感觉很不错对吧。
我们关于 TOML 的介绍就到此为止，现在来说一下我们这个初始化的新项目中的 pyproject.toml 文件要写成什么样。
就这样：
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "myproject"
version = "0.1.0"
description = "一个基于Python 3.13.3的项目"
readme = "README.md"
requires-python = ">=3.13"
authors = [
{name = "xiaobox", email = "xiaobox@gmail.com"}
]
dependencies = [
"pytest>=7.4.3",
"fastapi>=0.110.0",
"uvicorn>=0.27.0",
"httpx>=0.27.0",
]
classifiers = [
"Programming Language :: Python :: 3.13",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
[project.scripts]
myproject = "src.main:main"
[project.urls]
"Homepage" = "https://github.com/yourusername/myproject"
"Bug Tracker" = "https://github.com/yourusername/myproject/issues"
[project.optional-dependencies]
dev = [
"black>=23.1.0",
"isort>=5.12.0",
"mypy>=1.5.1",
]
[tool.pytest]
testpaths = ["tests"]
[tool.black]
line-length = 88
target-version = ["py313"]
[tool.isort]
profile = "black"
line_length = 88
[tool.hatch.build.targets.wheel]
packages = ["src"]
别小看了这个文件，它可是一个使用了 Hatch 构建工具、遵循 PEP 621 和现代 Python 项目结构规范的项目配置，涵盖了运行依赖、开发依赖、CLI 脚本、格式化工具配置、测试路径和打包目标，非常完整规范。
所以我们得逐行解释一下这个重要的文件。
我们上面的配置文件是一个标准的 Python 项目使用 pyproject.toml 来管理构建系统、依赖、工具配置的典型示例。下面我们来拆解和解释一下。
✅ [build-system]：构建系统配置（PEP 517 标准）
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
requires：构建该项目所需的构建工具，这里是 hatchling，必须先安装。build-backend：指定用哪个构建后端来执行打包任务，这里是 hatchling.build。hatchling 有点儿类似 java 中的 Maven 或 Gradle，都是用来执行自动化构建流程的。
总结来说：Python 的构建是将代码和依赖打包成 .whl 或 .tar.gz，类似于 Java 打包成 .jar。核心目的是简化分发、确保环境一致性、自动化依赖管理。
✅ [project]：项目的核心元信息（PEP 621 标准）
[project]
name = "myproject"
description = "一个基于Python 3.13.3的项目"
requires-python = ">=3.13"
authors = [
{name = "xiaobox", email = "xiaobox@gmail.com"}
]
dependencies = [
"pytest>=7.4.3",
"fastapi>=0.110.0",
"uvicorn>=0.27.0",
"httpx>=0.27.0",
]
classifiers = [
"Programming Language :: Python :: 3.13",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
[project.scripts]：定义可执行命令（如 CLI）[project.scripts]
myproject = "src.main:main"
myproject 命令会调用 src/main.py 中的 main() 函数。（我们需要提前把之前的 main.py 文件要先移动到 /src 目录下）[project.urls]：项目的相关链接（非必须）[project.urls]
"Homepage" = "https://github.com/yourusername/myproject"
"Bug Tracker" = "https://github.com/yourusername/myproject/issues"
[project.optional-dependencies]：可选依赖（比如开发环境）[project.optional-dependencies]
dev = [
"black>=23.1.0",
"isort>=5.12.0",
"mypy>=1.5.1",
]
我们为开发环境安装了三个库：black、isort 和 mypy
介绍一下这三个工具
[tool.pytest]：Pytest 配置[tool.pytest]
testpaths = ["tests"]
pytest 会从 tests/ 目录开始查找测试文件。[tool.black]：代码格式化工具 Black 的配置[tool.black]
line-length = 88
target-version = ["py313"]
[tool.isort]：import 排序工具 isort 的配置[tool.isort]
profile = "black"
line_length = 88
black 的风格对 import 排序。[tool.hatch.build.targets.wheel]：Hatchling 打包配置[tool.hatch.build.targets.wheel]
packages = ["src"]
src。用一句话总结下这个 pyproject.toml 配置文件 ：
“这是一个使用 Hatch 构建工具、遵循 PEP 621 和现代 Python 项目结构规范的项目配置，涵盖了运行依赖、开发依赖、CLI 脚本、格式化工具配置、测试路径和打包目标，非常完整规范。”
上面这个文件编辑完成后，我们就可以 安装项目和开发依赖了：
uv pip install -e ".[dev]"
如果后面你更新了 pyproject.toml 文件可以执行以下命令来 “手动刷新” 一个依赖库：
加入 --extra dev 参数是因为 uv sync 默认只安装 [project.dependencies] 中列出的正式依赖。
不会自动安装 [project.optional-dependencies]（比如 dev 里面的 black、isort、mypy）
uv sync --extra dev 的意思是：除了正式依赖，还要把 [project.optional-dependencies.dev] 里的东西也同步上
当执行完 uv sync --extra dev ，安装好依赖好， uv 会在项目根路径生成一个 uv.lock 文件 。uv.lock 是 锁定依赖版本 的文件。
它的作用是：把 pyproject.toml 里描述的依赖（比如 "fastapi>=0.110.0" 这样比较宽松的范围），具体锁定成明确、唯一的版本（比如 "fastapi==0.110.1"）。
这样，每次安装时，不管谁来安装（你自己、你的同事、你的服务器），大家安装的依赖版本都是一模一样的，不会因为小版本不同导致奇怪的 bug。
uv.lock 是自动生成、自动管理的。不需手动编辑。
其他的，如 fastapi 相关的、 打 docker 镜像部署什么的相对本文主题超纲了，就不在本文中过多描述了。
本文我们分享了用 uv 初始化和管理 Python 项目的完整流程。
从安装 uv 开始，我介绍了它为什么比传统工具（pip、pipx、poetry 等）更快更好用，以及 uv 在多 Python 版本管理、依赖锁定、项目初始化方面带来的便利。
随后，详细讲了如何用 uv 管理本地 Python 环境、新建项目、创建虚拟环境、编辑 pyproject.toml 配置，并逐步解释了各个配置项的作用
整体来看，uv 提供了一套现代、规范、高效的 Python 项目管理方案，非常适合用来打基础，后续无论是开发 API、打包 Docker 镜像，还是部署上线，都能有条不紊地进行。
同时我们通过在项目创建的过程中看到各语言（java、nodejs...）都相通或类似的工程 “最佳实践”，真是应了那句话：“大道至简，真理趋同”
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。