uv - python项目管理工具入门（含安装换源，项目管理，虚拟环境管理，常用命令，python项目打包发布，命令行指令注册）

为什么选择uv

一行代码让python项目的部署快10倍

  uv 可以通过一行代码让python环境的下载过程块10倍，如果不进行项目开发只是部署的话直接如下操作即可。

# 原来的pip命令
pip install -r requirements.txt/pyproject.toml

# 替换为
pip install uv
uv pip install -r requirements.txt/pyproject.toml

  如果想成为python项目开发人员请往下看。

官方文档

https://docs.astral.sh/uv/

  python 的虚拟环境管理一直是个让人头疼的问题，博主之前和大多数同学一样使用 conda 作为虚拟环境管理工具，直到在最近的实习中才慢慢体会到 uv 的优势。

1. 免费的虚拟环境管理工具（conda企业版收费）
2. 相较于conda，具有更清晰的第三方包的依赖关系（当删除一个第三方包时，会自动删除它的子依赖包）
3. 基于 rust 语言开发，兼容 pip 的使用命令，但运行速度会快上十倍左右（但是不太建议在项目开发时混用 pip 命令，会破坏项目的环境依赖文件）
4. 可以做为 python 的项目管理工具，支持一键打包成 whl 文件（可以上传发布到 pypi 平台）
5. 可以简化 cli 命令开发 （在 pyproject.toml 配置即可）

  最后，建议卸载 conda，使用纯粹的 uv，具体原因后面会说明。

安装

通过 uv 的安装工具全局安装（推荐）

macos 和 linux 系统

  根据实际情况以下命令3选1即可 ：

curl -LsSf https://astral.sh/uv/install.sh | sh # 使用curl
wget -qO- https://astral.sh/uv/install.sh | sh # 或者wegt
curl -LsSf https://astral.sh/uv/0.7.9/install.sh | sh # 指定安装版本

window 系统

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" 
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.7.9/install.ps1 | iex" # 安装指定版本

基于现有的 python 环境或者 conda 虚拟环境中安装（不推荐）

  虽然官方也支持了使用现有python环境安装uv，但是并不建议这样做，尤其是在 conda 的虚拟环境中使用 uv，因为现有环境中的第三方包和命令会干扰 uv 环境，带来一些混乱。

pipx install uv
pip install uv

给uv更换国内源

  uv 默认使用的是国外源，因为神秘力量的原因，可能会导致第三方包下载的比较慢，所以也需要向 conda 类似的换源操作。

  首先需要找到 uv 的配置文件位置（如果没有进行创建即可）：
  window 系统下为：C:\Users\你的用户名\AppData\Roaming\uv\uv.toml
  macos & linux 下为：~/.config/uv/uv.toml
  打开后插入以下代码段即可（老规矩，二选一）。

# 清华源
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

# 阿里源
[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true

项目管理

uv 项目结构说明

  uv 相较于 conda 的另一个优势是，uv可以作为项目管理工具。
  而一个 uv 管理的项目的基础结构如下：

项目名
--  src/ (自己创建，存放源码)
-- .vscode/ (vscode的调试配置文件)
-- .venv/ (存放当前项目的虚拟环境，后面介绍)
-- .gitignore (git 忽略文件列表，默认包含 .venv)
-- .python-version (uv run 等命令使用的 python 虚拟环境名/版本)
-- main.py
-- pyproject.toml (项目依赖管理文件，相当于requirements.txt plus版)
-- uv.lock （相较于 pyproject.toml 记录了项目依赖库的确切版本信息）
-- README.md

  其中大家可能会对 pyproject.toml 文件不太熟悉，toml 是一种与 python 更兼容的配置文件格式，类似于 yaml 和 json 文件。

version = ”v1“

[project]
name = "example"
version = "0.1.0"
dependencies = [] 

等价于 python 中的

version = ”v1“
project = {
	"name":"example", 
	"version":"0.1.0", 
	"dependencies":[] # 这个变量记载了当前项目的依赖包列表
}

创建一个新项目

  使用 uv init 命令会在当前目录下创建一个名为 langchain-learn 的项目文件夹，里面会自动生成 pyproject.toml，.gitignore，.python-version等文件。

uv init langchain-learn 
cd langchain-learn

等价于

mkdir langchain-learn
cd langchain-learn
uv init

打包一个python项目

  使用 uv build命令可以一键打包本项目为whl文件，以便于后续进行发布或者跨机器复现。
  具体的使用案例见下文中的 （需要先学会使用虚拟环境）

创建一个命令行入口函数（自定义cli指令和功能）

虚拟环境管理

   这里重新解释一下为什么不推荐在 conda 的虚拟环境里面使用 uv ，因为 uv 的理念与 nodejs 的包管理工具类似，都是在项目中创建一个专用于当前项目的虚拟环境，而 conda 则是创建全局可用的虚拟环境。所以 conda 虚拟环境中的包与 uv 管理的当前项目的依赖会有一定冲突。（uv 安装的包 conda环境一定可见，conda 安装的包 uv 未必可见 ）

创建、激活、退出虚拟环境

   使用以下命令后会在当前目录生成一个与系统环境独立的 .venv 文件夹，这里就是 uv 管理的虚拟环境。

uv venv 
uv venv py-name # 指定环境名，默认项目名
uv venv --python 3.11 # 指定版本号，默认使用.python-version文件的版本

   激活创建的虚拟环境。

# macos & linux
source .venv/bin/activate
# windows
.venv\Scripts\activate

   退出虚拟环境。

deactivate

创建一个命令行入口函数（自定义cli指令和功能）

  这里先举一个简单的例子，详细版以后再补充，例如在项目根目录的 src 目录下有一个模块叫 example ，我想在命令行中使用该模块的 hello 方法。

  首先需要在 pyproject.toml 文件中加入如下命令后即可在命令行中使用。

[tool.hatch.build.targets.wheel]
packages = ["src"]

[project.scripts]
hello = "example:hello"

[tool.uv]
package = true

  然后使用 uv 构建与安装项目，构建完成后项目根目录下会实现一个 dist 文件夹里面会包含对应本项目的 whl 文件。

uv build 

# 二选一安装环境
uv pip install dist\langchain_learn-0.1.0-py3-none-any.whl
uv sync

# 直接命令行运行即可，二选一
hello
uv run hello 

常用命令

  为了简化，第一行是 uv 命令，第二，三（如果有）是常用的python或者 pip/conda 命令参考（有对比会更容易记忆 ）

  同时uv 兼容 pip 命令。

uv运行相关

# 运行一个py脚本程序
uv run main.py 
python main.py

项目管理相关

# 创建一个新项目
uv init

# 打包当前项目，会生成一个whl文件
uv build

# 发布当前项目
uv publish

python 环境管理相关

# 创建虚拟环境
uv venv 
uv venv py-name # 指定环境名，默认项目名
uv venv --python 3.11 # 指定版本号，默认使用.python-version文件的版本

# 激活创建的虚拟环境。
# macos & linux
source .venv/bin/activate
# windows
.venv\Scripts\activate

# 退出虚拟环境。
deactivate

第三方依赖包管理相关

# 添加一个python包，使用 uv add 会同步写入 pyproject.toml 文件
# 使用uv pip install 安装的包可以通过 python 直接访问，但是不一定能被uv run访问。
uv add numpy
uv pip install numpy

# 删除一个python包，会同步从 pyproject.toml 文件中的该包以及其子依赖包。
# 注意：pip uninstall 不会删除子依赖包，只会删除指定包。
# 例如：uv remove 会删除安装torch附带安装的numpy包，pip不会。
uv remove torch 
uv pip uninstall torch

# 同步当前环境和项目环境，不在 pyproject.toml 中的包会被删除。
uv sync

# 展示第三方库的依赖关系
# uv 对版本关系按照树形记录，这也就是可以按照拓扑序删除子依赖的原因。
uv tree

# 导出第三方库的版本信息到 requirements.txt 文件
uv pip freeze > requirements.txt

# 列出已经安装的所有包
# 注意如果一个包是通过 pip install 而不是 uv add 安装
# 那么这个包虽然可以被列出，但是uv run的时候可能会报错缺失
uv pip list 

# 本地以可编辑模式安装一个包
uv pip install -e .

# 查看一个包的安装路径
uv pip show numpy