python包管理器uv工具的使用

原创

保持热爱奔赴山海

发布于 2025-11-24 22:21:11

1.1K0

文章被收录于专栏：DevOpsDevOps

项目地址 https://github.com/astral-sh/uv

优势：

uv 是用 Rust 编写的，其依赖解析和安装速度比 pip 快 10 到 100 倍。它支持并发下载、智能缓存和预编译二进制文件的优先选择。这意味着你的 CI/CD 流水线构建时间可以从几分钟缩短到几秒钟，极大地提升了开发和运维效率。
uv 通过 uv.lock 或 requirements.lock 文件精确锁定每一个直接和传递依赖的版本号以及其内容的哈希值。只要使用这个锁定文件进行安装（uv pip install -r requirements.lock），就能保证在任何机器、任何时间点安装的依赖树都是完全一致的。这对于生产环境的稳定性和可预测性至关重要。
uv 会对下载的每个包进行严格的哈希校验（SHA-256）。如果网络传输过程中数据损坏，或者仓库中的包被恶意篡改，uv 会立即检测到并报错，防止有问题的代码进入生产环境。
uv 拥有更先进的依赖解析算法，能够更快、更准确地找到满足所有约束的依赖组合，并提供清晰的错误报告，帮助你快速定位和解决问题。

安装

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

例如：
[root@vm-01 ~]# curl -LsSf https://astral.sh/uv/install.sh| sh
downloading uv 0.9.11 x86_64-unknown-linux-gnu
no checksums to verify
installing to /root/.local/bin
  uv
  uvx
everything's installed!

To add $HOME/.local/bin to your PATH, either restart your shell or run:

	source $HOME/.local/bin/env (sh, bash, zsh)
	source $HOME/.local/bin/env.fish (fish)



安装完成后按提示将 $HOME/.local/bin 加入 PATH（脚本通常会自动写入，如未写入可手动追加到 ~/.bash_profile 或 ~/.bashrc 并执行 source 使其生效）。

基本使用

创建工作目录

创建工作目录
mkdir ~/apps/code/ -pv
cd apps/code/
uv init demo  # 这个demo目录以后就是我们虚拟环境的家目录

或者  mkdir ~/apps/code/demo -pv && cd apps/code/demo && uv init

创建虚拟环境

使用命令 uv venv .venv 即可。
具体如下例子

切换到工作目录下
[root@vm-01 code]# cd demo/

可以看到有个git隐藏文件，还有些项目相关的文件
[root@vm-01 demo]# ls -la
total 16
drwxr-xr-x 3 root root 113 Nov 24 16:08 .
drwxr-xr-x 3 root root  18 Nov 24 16:08 ..
drwxr-xr-x 7 root root 119 Nov 24 16:08 .git
-rw-r--r-- 1 root root 109 Nov 24 16:08 .gitignore
-rw-r--r-- 1 root root   5 Nov 24 16:08 .python-version
-rw-r--r-- 1 root root   0 Nov 24 16:08 README.md
-rw-r--r-- 1 root root  82 Nov 24 16:08 main.py
-rw-r--r-- 1 root root 150 Nov 24 16:08 pyproject.toml

初始化一个虚拟环境，使用的是3.14.0版本的python
[root@vm-01 demo]# uv venv .venv --python=3.14.0  # 如果已存在，可以使用--clear强制覆盖掉  uv venv .venv --python=3.14.0 --clear
Using CPython 3.14.0
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

再次查看当前目录下的.venv虚拟环境目录，可以看到如下
[root@vm-01 demo]# ls -l .venv/bin/
total 40
-rw-r--r-- 1 root root 4079 Nov 24 16:09 activate
-rw-r--r-- 1 root root 2659 Nov 24 16:09 activate.bat
-rw-r--r-- 1 root root 2609 Nov 24 16:09 activate.csh
-rw-r--r-- 1 root root 4181 Nov 24 16:09 activate.fish
-rw-r--r-- 1 root root 3751 Nov 24 16:09 activate.nu
-rw-r--r-- 1 root root 2762 Nov 24 16:09 activate.ps1
-rw-r--r-- 1 root root 2383 Nov 24 16:09 activate_this.py
-rw-r--r-- 1 root root 1730 Nov 24 16:09 deactivate.bat
-rw-r--r-- 1 root root 1217 Nov 24 16:09 pydoc.bat
lrwxrwxrwx 1 root root   75 Nov 24 16:09 python -> /root/.local/share/uv/python/cpython-3.14.0-linux-x86_64-gnu/bin/python3.14
lrwxrwxrwx 1 root root    6 Nov 24 16:09 python3 -> python
lrwxrwxrwx 1 root root    6 Nov 24 16:09 python3.14 -> python

激活虚拟环境

[root@vm-01 demo]# source .venv/bin/activate

(.venv) [root@vm-01 demo]# python --version
Python 3.14.0

安装三方包

推荐使用uv add命令，注意加上 --python .venv/bin/python参数，确保包是安装到当前虚拟环境里面的。

例如：
uv add pip --python .venv/bin/python  # 建议先安装这个包，防止后续操作不小心用到其它环境中的pip包，导致当前虚拟环境被改动
uv add requests --python .venv/bin/python
uv add redis --python .venv/bin/python

查看配置清单,可以看到dependencies里面已经自动加进去了刚才的几个包了
(.venv) [root@vm-01 demo]# cat pyproject.toml 
[project]
name = "demo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
	"pip>=25.3",
	"redis>=7.1.0",
	"requests>=2.32.5",
]

安装包的其它方法「不推荐」

这种写法会可以确保在指定的 Python 环境中安装 pip，
但是它不会同步更新pyproject.toml文件，这是个大问题！！ 因此一般不要用 uv pip install 命令

uv pip install pip -p .venv/bin/python
同样的还有2种写法： 或 uv pip install ruff  或 uv pip install ruff -p .venv
uv pip 的用法和pip基本一样，只不过前面多了个uv命令而已。


看下pyproject.toml ，可以看到里面没有我们刚安装的pip包
(.venv) [root@vm-01 demo]# cat pyproject.toml 
[project]
name = "demo"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

其它

退出虚拟环境

deactivate

安装多个版本的python

uv python install 3.11 3.13

列出当前已安装的python版本和路径，还有可以下载的pyhon版本清单

uv python list
uv python list --all-versions
uv python list --only-installed

列出包之间的依赖关系

(.venv) [root@vm-01 demo]# uv tree
Resolved 8 packages in 1ms
demo v0.1.0
├── pip v25.3
├── requests v2.32.5
│   ├── certifi v2025.11.12
│   ├── charset-normalizer v3.4.4
│   ├── idna v3.11
│   └── urllib3 v2.5.0
└── ruff v0.14.6

根据pyproject.toml清单，安装相关的依赖（例如项目下载到其它环境去初始化部署）

uv sync

移除包

uv remove redis

uvx命令调用工具却不安装

注意
不会在当前虚拟环境中安装ruff，也不会修改pyproject.toml。
使用 UVX 时，工具会安装在临时且隔离的环境中

例如
uvx ruff check 等价于 uv tool run ruff check

uvx执行命令的时候指定python版本

uvx --python 3.14 ruff check

uv.lock文件的含义

它是一个跨平台的 lockfile，包含你项目依赖的准确信息。
与用于指定项目广泛需求的 pyproject.toml 不同，lockfile 包含了项目环境中安装的具体已解析版本。
该文件应被提交到版本控制中，以便实现跨机器的一致且可重复的安装。
uv.lock 是一个人类可读的 TOML 文件，但由 UV 管理，不应手动编辑。

导出uv.lock 适配其它依赖包场景

uv export --format requirements.txt --output-file requirements.txt
uv export --format pylock.toml --output-file pylock.toml
uv export --format cyclonedx1.5 --output-file sbom.json

为了避免每次都输入参数 --python .venv/bin/python ，可以做了软链接

# 在 ~/.bashrc 或 ~/.zshrc 中创建别名
alias uvsa='uv add --python .venv/bin/python'
alias uvs='uv sync --python .venv/bin/python'

使用别名（更安全）
uvsa requests pandas

注意

如果手动编辑 pyproject.toml 后，需要执行 uv lock 和 uv sync ，确保环境是和配置文件一致的。
一般不要使用 uv add 因为如下原因：

uv add 是为 pyproject.toml 项目设计的命令。

它会触发 uv 的“项目管理模式”，可能会创建或切换到它自己管理的缓存环境（如 ~/.cache/uv/...）【很重要，可能导致你的虚拟环境被切换成其它的】。

它还会修改 pyproject.toml 文件，如果您只是想临时安装一个工具（如 ruff, jupyter），这会污染您的项目配置。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

python

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

python

登录后参与评论

0 条评论

热度