Python 包管理工具 uv 使用指南

1、初始化项目

uv init projectName

执行后就会在相应目录初始化一个项目，其目录结构如下： ├── .gitignore ├── .python-version ├── README.md ├── main.py └── pyproject.toml

在已有文件夹下初始化项目

cd /目标目录/projectName
uv init

此方式也可以在已有代码的目录下初始化，并使用 uv run main.py 自动创建 .venv 环境

2、安装 Python

uv python install
Installed Python 3.12.12 in 4.07s + cpython-3.12.12-windows-x86_64-none

查看可安装的 Python 列表

uv python list

安装指定版本的 Python

uv python install 3.14

查找已安装的 Python

uv python find

3、运行 main.py

uv run main.py
Using CPython 3.12.12
Creating virtual environment at: .venv
Hello from project1

第一次运行，他还会自动创建 .venv 环境，环境目录创建后，项目的完整路径如下： . ├── .venv │ ├── bin │ ├── lib │ └── pyvenv.cfg ├── .python-version ├── README.md ├── main.py ├── pyproject.toml └── uv.lock

注意：.venv 目录请勿加入版本管理。当然 uv 已为我们自动创建好了 .gitignore 文件，并排除了该目录。

uv 管理依赖

我们这里以添加 numpy 依赖为示例展示

添加依赖

uv add numpy

执行后 uv 会自动管理 pyproject.toml 文件，并添加 numpy 依赖

升级依赖

uv lock --upgrade-package numpy

移除依赖

uv remove numpy

查看依赖树

uv tree

查看项目版本

# 完整版本
uv version
# 简单版本
uv version --short
# 格式化输出
uv version --output-format json

项目移植

将别人使用 uv 管理的项目代码、环境移植到本地（企业环境中项目开发）

# 使用 sync 同步依赖
cd (通过 git 等同步的项目根路径)
uv sync
# 激活环境
.venv\Scripts\activate

不同的平台激活环境

Linux

uv sync
source .venv/bin/activate

Windows

uv sync
.venv\Scripts\activate

项目打包

uv build

命令执行后，项目打好的包会在项目根路径的 dist 目录下

uv 的常用内容就到此了，其余还有 tools (uvx) 管理等，可直接到官网深入学习