使用 uv 进行 python 项目管理

文章目录

• [Why UV？](#Why UV？)
• [安装 Installation](#安装 Installation)
• [UV 项目开发](#UV 项目开发)
• • 项目结构
  • 依赖包管理
  • [Python 环境管理](#Python 环境管理)
• [UV 项目构建和发布](#UV 项目构建和发布)

Why UV？

• 通过 pyproject.toml he uv.lock 文件进行项目依赖管理，同时允许开发者在项目中进行不同 python 环境的管理和切换，单一命令实现完整的项目管理，无需 pip，venv 等其他工具。
• 比 pip 10 倍以上更加便利快捷的依赖包管理

安装 Installation

Linux 和 MacOS 上的安装命令：

 curl -LsSf https://astral.sh/uv/install.sh | sh

windows 安装命令：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

其中， -ExecutionPolicy ByPass 用于临时修改 Windows 的安全策略限制，允许在 PowerShell 中执行 psl 脚本。

安装完成之后，默认情况下终端并不了解 uv 的命令补全规则，需要额外让终端在启动时加载 uv 的补全规则：

echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc

Windows:

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

安装完成之后，可以直接运行 uv 命令，查看 help 内容。

UV 项目开发

项目结构

项目是 uv 的核心概念，通过 uv init [your-project-name] 可以初始化创建一个项目，初始化的目录结构如下：

.
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

例如 uv init hello-world：

其中，main.py 文件为主入口文件，包含简单的示例代码：

def main():
    print("Hello from hello-world!")


if __name__ == "__main__":
    main()

uv 通过一个 pyproject.toml 文件来描述这个 uv 项目，这是 uv 项目的核心文件，包含了这个项目的所有元数据比如项目名称、依赖等内容：

[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.13"
dependencies = []

通过执行 uv run main.py 可以执行 python 脚本：

执行之后，项目下会额外生成一个 uv.lock 锁文件以及 .venv/ 目录：

其中：

• uv.lock 是 uv 项目依赖的 python 包的版本信息锁文件，
• .venv/ 是管理项目的 python 虚拟环境的文件夹，与系统的其他 python 环境相互隔离，uv 可以允许用户在一个项目中进行不同 python 环境的切换。初始化项目之后，默认的 python 环境是 uv 安装时携带的 python 环境，可以通过 uv python 命令查看当前项目的 python 环境，进行其他版本的 python 环境安装，切换环境等管理操作

初始化完成之后，后续就可以根据具体项目需求，使用 flask 等后台代码框架进行应用代码的初始化和开发了。

依赖包管理

uv 安装依赖包的方式如下

uv add [package]
uv pip install flask

可以使用与 pip 一样的方式使用 ==, >=, <=指定版本，或者版本条件安装进行安装：

uv pip install 'ruff>=0.2.0'

一些依赖包设置了额外的依赖选项，需要通过 package[option] 的方式指定依赖项安装：

uv pip install "flask[dotenv]"

Python 环境管理

uv 项目中，一般通过 uv venv 创建虚拟环境（类似 conda）：

uv venv --python 3.12

使用 uv python 命令进行 python 环境管理：

# 常用，安装指定版本
uv python install [version]
uv python install 3.12

# 根据项目要求安装满足条件的版本
uv python install '>=3.8,<3.10'

# 安装多版本
uv python install 3.9 3.10 3.11

UV 项目构建和发布