Ubuntu / WSL 安装pipx uv
一、安装pipx
在 Ubuntu / WSL 上可以用两种方式安装，推荐第二种（官方脚本）或第三种（pip 安装最新版本并自动配置 PATH）。
1.1、apt 安装（最快，但版本往往偏旧）
sudo apt update
sudo apt install pipx
# apt 默认把可执行文件装在 /usr/bin/pipx
如果只是想临时体验可以这么做，但通常 apt 源里的 pipx 版本落后，且不会帮你配置用户路径。
1.2、官方一键脚本（最新版 + 自动配置）
python3 -m pip install --user pipx
python3 -m pipx ensurepath # 把 ~/.local/bin 写进 PATH
解释：
--user把 pipx 安装到~/.local下，避免 sudo；ensurepath会在~/.bashrc、~/.zshrc等文件尾部追加
让之后所有终端都能直接用# added by pipx export PATH="$HOME/.local/bin:$PATH"pipx命令。
执行完后：
- 重新开一个终端（或
source ~/.bashrc），再试：pipx --version
1.3、纯 pip + 手工 PATH（万一网络受限）
python3 -m pip install --user pipx
# 手动把 ~/.local/bin 加到 PATH，并重开终端
export PATH="$HOME/.local/bin:$PATH"
把上面 export 语句写进 ~/.bashrc 或 ~/.zshrc 即可。
二、使用pipx 安装 poetry 生成 pyproject.toml 文件
2.1 、Poetry（最流行的 All-in-One）
-
安装
pipx install poetry -
在现有目录里交互式生成
poetry init # 逐步问答，最后生成 pyproject.toml• 新项目直接
poetry new --src mypkg，骨架（src 目录、tests、pyproject）一次到位。 -
后续操作
# 安装依赖 poetry add fastapi ... # poetry install # 创建虚拟环境并安装依赖 # poetry build # 打包 wheel / sdist
2.2、Hatch（官方推荐的新一代工具）
-
安装
pipx install hatch -
生成项目模板
hatch new mypkg会得到：
mypkg/ ├─ src/mypkg/__init__.py ├─ tests/ └─ pyproject.toml ← 已写好 build-system + project 字段 -
依赖管理
cd mypkg hatch env create hatch run +dev:pytest hatch build
以下是关于 Python 管理工具 uv 和 uvx 的详细介绍，包括核心功能、使用方式及常见命令：
三、uv 与 uvx 概述
uv 是由 Astral 团队开发的 Rust 编写的 高性能 Python 包和环境管理工具，旨在替代 pip、virtualenv、pip-tools 等工具。其核心优势包括：
- 极速性能：依赖解析和包安装速度比
pip快 10-100 倍。 - 集成化功能：整合虚拟环境管理、依赖锁定、Python 版本管理、工具运行等。
- 轻量级设计：自动识别
.venv目录，无需手动激活环境。
uvx 是 uv tool run 的别名，用于 在隔离环境中临时运行 Python 工具（如 ruff、black），无需全局安装。
3.1、安装 uv
3.1.1 通过独立脚本安装（推荐）：
# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows（PowerShell）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
3.1.2 通过 pipx 安装：
pipx install uv
3.1.3 验证安装：
uv --version
3.2、uv 核心功能与命令
uv 官方doc
3.2.1 虚拟环境管理
- 创建虚拟环境：
uv venv # 默认创建 .venv 目录 uv venv --python 3.11 # 指定 Python 版本
在当前目录创建 .venv 虚拟环境（类似 python -m venv .venv），无需手动激活，uv 命令会自动识别并使用它。
- 删除虚拟环境：
uv venv --remove .venv
3.2.2 依赖管理
- 同步依赖：
uv sync # 根据 pyproject.toml 同步环境 - 依赖锁定：
uv pip sync requirements.txt
3.2.3 项目管理
- 初始化项目：
uv init myproject # 生成 pyproject.toml 和 .python-version - 添加/移除依赖：
uv add flask # 添加生产依赖 uv add --dev pytest # 添加开发依赖 uv remove fastapi # 移除依赖
3.2.4 Python 版本管理
- 安装 Python：
uv python install 3.11 # 安装指定版本 - 查看已安装版本：
uv python list
3.2.5 初始化项目示例
# 1. 创建并初始化目录
uv init example # 创建了一个 example 的项目
cd example # 跳转到该项目内
# 2. 当前目录下安装 .venv 环境
uv venv --python 3.11 # 安装指定python版本的环境
source .venv/bin/activate # 激活虚拟环境
# 3. 添加一些包
uv add fastapi # 类型pip install，添加 fastapi包
# 4. 同步
uv add ruff
uv run ruff check
# All checks passed!
uv lock
uv sync
# 查看安装的包
uv pip list
#source .venv/bin/activate
#uv sync --active
3.2.6 uv安装包：uv pip 与 uv add 的区别
- 用
uv add xxx安装，包会被写进你的依赖文件，团队成员一同步代码就能看到项目需要这个包。 - 用
uv pip install xxx，只是把包装进当前环境，但依赖文件里没有这个包的记录，以后别人同步依赖或者清空环境重装时，这个包就不会自动被安装，需要手动加回。
总结
- “临时”=只装进环境、不记录依赖，不会自动删除，除非你手动卸载或者重新创建环境。
- 如果想试完就删，可以自己运行
uv pip uninstall xxx - 如果想安装后自动删除，可以写个脚本，但
uv本身不会自动卸载。
拓展举例
- 安装并试用（不会记录依赖文件）：
uv pip install somepkg # 用完可以卸载 uv pip uninstall somepkg # 从 requirements.txt 安装依赖 uv pip install -r requirements.txt # 升级已有包 uv pip install --upgrade uvicorn # 查看当前安装的包 uv pip list # 导出依赖（冻结） ## uv pip freeze > requirements.txt uv pip list --format=freeze > requirements.txt # 查看包信息 uv pip show fastapi # 清理缓存 uv pip cache purge - 安装并记录到项目（推荐团队项目）：
uv add somepkg # 会写入 pyproject.toml 或 requirements.txt
四、uvx 工具运行
1、 基础用法
- 运行工具：
uvx ruff . # 运行最新版 Ruff uvx black@latest # 强制使用最新版 uvx ruff@0.3.0 check # 指定版本 - 处理包名与命令名不同：
uvx --from httpie http # 包名为 httpie，命令为 http
2、高级功能
- 安装额外依赖：
uvx --with mkdocs-material mkdocs # 包含插件 - 从 Git 源运行：
uvx --from git+https://github.com/httpie/cli@master httpie
3、安装工具到全局
若需频繁使用某工具，可全局安装：
uv tool install ruff # 安装到 PATH
uv tool upgrade ruff # 升级
4、uv 与 uvx 对比
| 场景 | uv 命令 | uvx 命令 |
|---|---|---|
| 运行脚本 | uv run py文件 | |
| 运行临时工具 | uv tool run <工具名> | uvx <工具名> |
| 指定工具版本 | uv tool run tool@版本 | uvx tool@版本 |
| 全局安装工具 | uv tool install | 不适用 |
| 包含额外依赖 | uv tool run --with | uvx --with |
5、常见问题与注意事项
- 环境隔离：
uvx默认在临时环境中运行工具，与项目依赖隔离。若需访问项目依赖（如运行pytest），应使用uv run。
- 缓存机制：
uv缓存依赖以提高性能，可通过uv cache clean清理缓存。
- 兼容性：
uv pip命令兼容传统pip工作流，但部分高级功能可能略有差异。
五、参考文献：
- 使用 uv 管理 Python 環境
