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

[jiakai]

uv工具的安装：

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

[jiakai]

# 查看uv的版本
uv --version

[jiakai]

# 将uv更新到最新版本
uv self update

[jiakai]

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

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

[jiakai]

1、使用虚拟环境

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

[jiakai]

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

[jiakai]

# 安装 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作为虚拟环境目录。

[jiakai]

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

[jiakai]

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

via: Python versions | uv

[jiakai]

uv add python_pacakge vs uv pip install python package：

uv sync命令的解释：

[jiakai]

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

Build an MCP server - Model Context Protocol

[jiakai]

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 应用程序/工具。

[jiakai]

uv的缓存机制：

# 清除整个uv缓存
uv cache clean

[jiakai]

# 清理 uv 包管理器的缓存
uv cache prune

[jiakai]

uv cache clean和uv cache prune区别：

[jiakai]

uv管理python环境的自动激活机制。

[jiakai]

# 升级并同步所有依赖包到最新版本
uv sync --upgrade