【Python】开发工具uv

1. uv install

1.1 下载安装脚本来安装

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

# 用wget
wget -qO- https://astral.sh/uv/install.sh | sh

1.2 使用pipx安装uv

补充：pipx是安全地安装和运行隔离的 Python 命令行工具，它能够解决全局安装python应用（ pip install --user 或 sudo pip install）的依赖冲突和环境污染问题。

sudo pip install <pkg>
安装的可执行文件位置：/usr/local/bin
安装的库文件位置：
/usr/local/lib/pythonX.X/dist-packages/ (Debian/Ubuntu)
/usr/lib/pythonX.X/site-packages/ (RHEL/CentOS)

pip install --user <pkg>
安装的可执行文件位置：~/.local/bin/
安装的库文件位置：~/.local/lib/pythonX.X/site-packages/

pipx install <pkg>
将每个工具安装在独立的虚拟环境中
~/.local/pipx/venvs/flake8/     # flake8 的独立环境

# 先安装pipx
sudo apt install pipx

# 再安装uv
pipx install uv
pipx ensurepath && source ~/.basrc

1.3 补充

• pipx依赖venv，需要确保venv全局安装。sudo apt install python3.8-venv
• pip安装提示，Not installing to existing directory。可能是之前失败安装存在残留文件。pipx install --force
• 安装uv后还需要将可执行文件目录添加到$PATH。执行pipx ensurepath可以自动把pipx下载的工具的可执行文件目录都添加到$PATH

2. 考虑在离线系统上安装uv

2.1 下载并上传安装包

# 使用pip下载，.whl安装包在当前目录，可能有多个.whl文件，所以打包
pip download uv
cd .. && tar -zcvf uv.tar.gz uv/

scp uv.tar.gz cg@192.168.250.234:~/Downloads/

2.2 用户级安装uv（~/.local/bin/）

# 解压
cd ~/Downloads/
tar -zxvf uv.tar.gz

# 安装到用户级site-package
pip install --no-index --find-links=~/Downloads/uv uv
--no-index：禁止从 PyPI 下载。
--find-links=.：从当前目录查找包。

# 添加~/.local/bin到$PATH
echo 'export PATH=$HOME/.local/bin:$PATH'

2.3 补充

Q：安装包为uv-0.7.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl，包名：uv；包版本：0.7.3；python兼容版本：python3；abi标签：none，表示不依赖python abi（不依赖任何扩展的纯python包）；架构：x86_64;系统兼容性：manylinux标准（manylinux_2_17和manylinux2014）。目标机器架构为arm，无法安装这个安装包。
A：确认安装包的平台版本和目标系统平台兼容，目标系统是x86_64的，则安装包应该是x86_64d的， 目标系统是arm结构的，安装包应该是arm架构的。

3. uv 管理Python解释器

# 查看uv可安装和已经安装的python版本
uv python list

# 安装指定版本的python，安装位置 /home/user01/.local/share/uv/python/
uv python install cpython-3.12

# 使用已安装的某个版本的python解释器执行
uv run -p 3.12 main.py

# 使用已安装的某个版本的python解释器进入交互式执行环境
uv run -p 3.12 python

ps: uv指定python解释器版本时，如果uv没有安装之，则会自动安装它

4. uv 管理依赖

# 创建工程
mkdir test && cd test
uv init -p 3.12

# 目录树
tree
├── .git
├── .gitignore
├── .python-version  # 3.12
├── README.md
├── main.py
└── pyproject.toml  # 跟踪项目当前依赖

# 假设项目源码文件依赖和pyproject.toml记录的不一样
uv sync

5. 用uv执行脚本

5.1 使用显式指定的依赖

假设pyproject.toml记录已经安装了requests
# main.py
import requests
import aithttp

if __name__ == '__main__':
    url = 'www.baidu.com'
    resp = requests.get(url)
    print(resp.text)
    print(aiohttp.__version__)

# 可以从pyproject.toml中找到requests，但是找不到 aiohttp。
uv run main.py

# 可以从pyproject.toml中找到requests，并且显示给定了依赖aiohttp，正常运行。aiohttp被下载到~/.cache/uv
uv run --with aiohttp main.py

# 此时忽略 pyproject.toml，requests 和 aiohttp 都找不到。
uv run --no-project main.py

5.2 使用项目的依赖

# 可以从pyproject.toml中找到requests，但是找不到 aiohttp。
uv run main.py

# 执行脚本，使用项目的虚拟环境维护依赖
uv add aiohttp  # 登记 aiohttp 及其依赖到 pyproject.toml 
uv run main.py  # 此时 pyproject.toml 记录了 aiohttp 和 requests，正常执行。

# 从项目中删除依赖
uv remove requests

PS: 使用uv查看项目的依赖关系

uv tree

test v0.1.0
└── requests v2.32.3
    ├── certifi v2025.4.26
    ├── charset-normalizer v3.4.2
    ├── idna v3.10
    └── urllib3 v2.4.0

5.3 使用脚本自己维护的依赖

# 脚本自己加上所需依赖
uv add --script main.py requests

# uv将往main.py头插入记录依赖信息的注释
# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "requests",
# ]
# ///

import requests

if __name__ == '__main__':
    url = 'https://www.baidu.com'
    resp = requests.get(url)
    print(resp.text)

# 执行，以脚本模式运行，即使在uv项目中也可以不加--no-project而运行
uv run --script main.py

5.4 总结

• uv初始化项目后首次执行run会先创建项目虚拟环境：.venv。
• uv run xxx.py 将使用项目依赖（使用项目的虚拟环境.venv）运行。
• uv run --with xxx将使用项目虚拟环境（.venv）和临时环境（~/.cache/uv，在临时环境中找--with指示的依赖）运行。
• uv run --no-projecy main.py 将会使用临时环境（~/.cache/uv）运行。
• uv run --script main.py将使用临时环境（~/.cache/uv）运行，不过脚本自己能够记录依赖信息，使用uv add --script main.py添加依赖，使用uv remove --script main.py 删除依赖。

6. python开发工具管理

开发需要python工具，可将这些工具添加到项目依赖，但这些工具不应该随其他项目依赖打包。
uv add flake8 --dev

但是实际工程中，这些工具应该与项目无关，需要在其他地方维护。另外即使通过–dev可以避免项目打包时把工具打包进去，但是添加工具时可能添加工具自己的依赖到项目中而污染了项目的虚拟环境。正确做法时使用uv tool来维护这些工具。

# 工具安装到~./cache/uv/
uv tool install flake8

# 查看已经安装的工具
uv tool list

7. 项目打包为.whl文件

# pyproject.toml文件中添加session
[project]
name = "p10-tmp"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = []

[prject.scripts]
test = ["test:main"]


# 打包
uv build 
dist
├── p10_tmp-0.1.0-py3-none-any.whl
└── p10_tmp-0.1.0.tar.gz


# 安装离线包
uv tool install dist/p10_tmp-0.1.0-py3-none-any.whl

补充

Q&A
Q：pip如何确定package安装到系统目录还是用户目录
A：pip根据以下要素判断该把package放到哪里：

1. 是否添加–user参数：加–user参数，package放到用户级site-package中
2. 是否处于虚拟环境激活状态：虚拟环境激活状态，package放在虚拟环境的site-package中
3. 普通用户还是特权用户（root用户或者sudo pip install）：普通用户则放在用户的site-package，特权用户则放在系统site-package中。
   注意，普通用户执行pip install 等价于pip install --user .

more about pip

• --user parameter
pip install --help
–user: Install to the Python user install directory for your platform. Typically ~/.local/, or %APPDATA%\Python on Windows. (See the Python documentation for site.USER_BASE for full details.)

• pip’'s doc
https://packaging.python.org/en/latest/tutorials/installing-packages/