uv_learn

包管理器：UV

包管理器就是在python项目中，管理各种依赖的安装和卸载，环境的构建，方便开发者能够不被各种版本依赖困扰。uv是使用rust语言开发的一款包管理器，使用起来非常便捷，最大的感受是安装各种包的时候速度非常的快。

安装

使用pipx安装

• pipx install uv

使用uv新建一个项目

• mkdir proj
• cd proj
• uv init：创建项目的基本文件
• uv venv：创建虚拟环境

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

接下来我们可以使用uv pip install 安装包，但是这样安装的包的信息不会立即同步到toml文件和lock文件中，如果使用uv add package命令，则可以让包在安装好后，相关星系能够同步到toml文件和lock文件。

其中toml文件在刚创建好的时候会包含项目的元信息，系统依赖项，构建系统的要去比如：

[project]
name = "uv-test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "numpy>=2.3.1",
    "pandas>=2.3.0",
    "pillow>=11.2.1",
]

其中lock文件是依赖锁文件，记录所有依赖项及其精确版本，确保在不同平台上可复现的安装，这个是uv自动管理的，无需手动编辑:

[[package]]
name = "numpy"
version = "2.3.1"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://files.pythonhosted.org/packages/2e/19/d7c972dfe90a353dbd3efbbe1d14a5951de80c99c9dc1b93cd998d51dc0f/numpy-2.3.1.tar.gz", hash = "sha256:1ec9ae20a4226da374362cca3c62cd753faf2f951440b0e3b98e93c235441d2b", size = 20390372, upload-time = "2025-06-21T12:28:33.469Z" }
wheels = [
    { url = "https://files.pythonhosted.org/packages/b0/c7/87c64d7ab426156530676000c94784ef55676df2f13b2796f97722464124/numpy-2.3.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6ea9e48336a402551f52cd8f593343699003d2353daa4b72ce8d34f66b722070", size = 21199346, upload-time = "2025-06-21T11:47:47.57Z" },
    ## 后面还有一大堆

[[package]]
name = "pandas"
version = "2.3.0"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "numpy" },
    { name = "python-dateutil" },
    { name = "pytz" },
    { name = "tzdata" },
]
sdist = { url = "https://files.pythonhosted.org/packages/72/51/48f713c4c728d7c55ef7444ba5ea027c26998d96d1a40953b346438602fc/pandas-2.3.0.tar.gz", hash = "sha256:34600ab34ebf1131a7613a260a61dbe8b62c188ec0ea4c296da7c9a06b004133", size = 4484490, upload-time = "2025-06-05T03:27:54.133Z" }
wheels = [
    { url = "https://files.pythonhosted.org/packages/96/1e/ba313812a699fe37bf62e6194265a4621be11833f5fce46d9eae22acb5d7/pandas-2.3.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:8adff9f138fc614347ff33812046787f7d43b3cef7c0f0171b3340cae333f6ca", size = 11551836, upload-time = "2025-06-05T03:26:22.784Z" },

• source .venv/bin/activate: 激活环境
• 使用uv add来安装包
• 安装完使用uv sync来进行同步，这个命令会优先根据lock文件来安装依赖

使用uv从已有项目中构建环境

如果以及有一个项目，这个项目使用toml文件写明了项目需要的依赖，可以使用uv来快速的构建项目

• 首先创建一个虚拟环境:uv venv，然后激活
• 运行命令：uv pip install .:uv 会在当前目录下的toml文件，根据它来安装所有的依赖
• uv lock：可选，生成uv.lock文件

使用uv从requirements.txt中构件环境

如果克隆了一个项目，这个项目使用的是requirements.txt文件作为项目依赖说明，遵循以下步骤可以构件环境：

• 首先确定运行uv init和uv venv，创建好环境，source 激活环境
• 使用命令uv pip install -r requirements.txt会将requirements中的依赖都安装到环境中，但注意此时是临时安装，因为pyproject.toml文件中并没有显示这些依赖。这里涉及uv的理念，pyproject.toml中写明的依赖是本项目完成后，确实需要的依赖，相当于一个账本将本项目能正常运行所需要的依赖全部记录了下来。但是在开发过程中，我们可能会不断的安装某些依赖，当最后项目完成的时候某些依赖可能是不需要的。所以uv这里并不会自动的将安装到环境中的依赖全部同步到pyproject.toml这个依赖声明中。
• 如果确定requirement.txt中的全部依赖都是项目需要的依赖，我们需要补记账，此时运行uv add $(cat requirements.txt)或者uv add -r requirements.txt

正确的 uv + requirements.txt 迁移流程（标准范式）

# 1. 初始化 uv 项目
uv init

# 2. 创建虚拟环境
uv venv

# 3. 从 requirements.txt 导入为项目依赖
uv add -r requirements.txt

# 4. 以后只用这一条
uv sync

uv synv、uv add和uv pip install

在uv的开发理念中，项目中有两个东西，一个是项目声明，是一个项目依赖清单，即文件pyproject.toml.另一个是环境状态，即环境中实际装了什么，这个在uv.lock或者venv中可以查看。

• uv pip install xxx 就是改变环境状态，安装某个包到环境中，但这个包不一定是本项目所必须的，所以该命令不会改变pyproject.toml
• uv add xxx 手动修改项目声明，该命令添加包之后，这个包就会进入到pyproject.toml中，即认为这个包是项目所必须的，此时uv.lock也会更新
• uv sync：根据toml文件和uv.lock，强制同步环境，安装toml文件中所有的依赖，删除当前环境中没有声明的包（即不在toml文件中），让环境状态等于项目声明，所以非常适合用在刚把一个项目克隆下来的时候使用，确保环境一致。

总结表格如下：

命令	是否改 pyproject.toml	是否装包	是否更新 uv.lock	定位
uv pip install	❌	✅	❌	临时 / 兼容 pip
uv add	✅	✅	✅	正式依赖管理
uv sync	❌	✅（同步）	❌	环境对齐