每日分享14：python包管理器uv的基本使用

常规
1

uv工具的安装：

curl -LsSf https://astral.sh/uv/install.sh | sh
2 
# 查看uv的版本
uv --version
3 
# 将uv更新到最新版本
uv self update
4

当然有关uv的用法还有很多。
https://docs.astral.sh/uv/

等到后期用到python项目时再来补充，需要用再学效率更高。

5

1、使用虚拟环境

# 创建名为pelican的虚拟环境并指定python版本。
uv venv pelican --python 3.12
# 激活pelican虚拟环境
source pelican/bin/activate
# 将软件包安装到虚拟环境中
uv pip install "pelican[markdown]"
6

重写写一下基本使用，主要用于虚拟环境，使用起来确实相较于conda更快。

7 
# 安装 uv 包管理工具
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建集中管理的虚拟环境目录
# mkdir -p ~/.venvs

# 在该目录下创建项目虚拟环境
uv venv ~/.venvs/docling-env --python 3.12 

# 激活虚拟环境
source ~/.venvs/docling-env/bin/activate

# 安装 docling 包
uv pip install docling

可以参考这个集中管理虚拟环境的方式，也可以在各自对应的项目中新建.venv作为虚拟环境目录。

8

pip环境迁移到uv环境的命令：

1748×1592 111 KB

9

新建虚拟环境时，不指定python版本，uv的行为：

1238×1328 75 KB

1242×1556 85.3 KB

via: Python versions | uv

10

uv add python_pacakge vs uv pip install python package：

1284×1990 148 KB

uv sync命令的解释：

1268×1590 132 KB

11

uv的实操也可以参考mcp中的quick start，里面的命令就是一些uv的基本操作。

12

uv pip install vs uv tool install vs uv add【下方为Gemini 2.5 Pro讲解】

uv tool install, uv pip install, uv add 的区别与联系

这三个命令都利用了 uv 高效的包解析和安装能力，但它们服务于不同的目的，操作的环境和影响也不同。

1. uv pip install

  • 目的: 作为 pip install 的直接替代品，用于在当前激活的 Python 环境（通常是项目虚拟环境）中安装包。
  • 行为:
    • 读取指定的包名、requirements.txt 文件或 pyproject.toml 中的依赖项。
    • 解析并安装这些包及其依赖项到当前环境中。
    • 不修改 pyproject.toml 文件来记录依赖关系（除非是根据 pyproject.toml 进行安装）。
  • 类比: 类似于传统的 pip install。
  • 使用场景:
    • 快速安装一个临时需要的包进行测试。
    • 根据 requirements.txt 或 pyproject.toml 文件安装项目依赖。
    • 在脚本或 CI/CD 流程中安装依赖。

2. uv tool install

  • 目的: 用于安装 Python 命令行工具或应用程序，并将它们安装在隔离的环境中，使其可以在系统范围内或用户级别方便地调用，而不污染项目环境或全局 Python 环境。
  • 行为:
    • 为指定的工具创建一个独立的、隔离的虚拟环境。
    • 将工具及其依赖安装到这个隔离环境中。
    • 通常会将该工具的可执行文件链接到一个位于系统 PATH 路径下的目录（如 ~/.local/bin），方便直接调用。
  • 类比: 类似于 pipx install。
  • 使用场景:
    • 安装你想在任何地方都能运行的 Python 工具，例如 ruff, black, httpie, ansible 等，而不想让它们的依赖影响你的项目。

3. uv add

  • 目的: 在当前项目环境中安装一个包，并且同时将其添加为项目的显式依赖项，记录在 pyproject.toml 文件中。
  • 行为:
    • 安装指定的包及其依赖项到当前激活的虚拟环境中。
    • 修改 当前目录下的 pyproject.toml 文件，将该包添加到 [project.dependencies] 或 [project.optional-dependencies] 下（取决于是否使用了 --optional 等参数）。
  • 类比: 类似于 poetry add 或 pdm add 或 npm install <package> --save。
  • 使用场景:
    • 为你的项目添加一个新的运行时或开发依赖项，并希望这个依赖关系被持久化记录和管理。

总结与对比

特性 uv pip install uv tool install uv add
主要目的 安装包到当前环境 安装命令行工具到隔离环境 安装包到当前环境并记录到 pyproject.toml
目标环境 当前激活的 Python 环境 (通常是 venv) 为每个工具创建独立的隔离环境 当前激活的 Python 环境 (通常是 venv)
修改pyproject.toml? 否 否 是
类比工具 pip install pipx install poetry add, pdm add
典型用例 安装项目依赖、临时安装包 安装全局可用的 Python CLI 工具 为项目添加新的、需要管理的依赖项

联系:

  • 三者都使用 uv 的底层引擎进行快速的依赖解析和安装。
  • uv pip install 和 uv add 都作用于当前的项目环境，但 uv add 额外承担了维护 pyproject.toml 的责任，更侧重于声明式依赖管理。uv pip install 更像是执行安装动作本身。
  • uv tool install 则完全不同，它关注的是工具的安装和隔离，而非项目依赖。

简单来说：

  • 用 uv add 来管理你项目代码直接依赖的库。
  • 用 uv pip install -r requirements.txt 或 uv sync (如果使用 uv 管理依赖) 来根据配置文件安装项目依赖。
  • 用 uv tool install 来安装你希望全局使用的 Python 应用程序/工具。
13

uv的缓存机制：

2370×2076 181 KB

# 清除整个uv缓存
uv cache clean