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

解释：

1. --user 把 pipx 安装到 ~/.local 下，避免 sudo；
2. 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）

1. 安装

   pipx install poetry    
   

2. 在现有目录里交互式生成

   poetry init             # 逐步问答，最后生成 pyproject.toml
   

   • 新项目直接 poetry new --src mypkg，骨架（src 目录、tests、pyproject）一次到位。

3. 后续操作

   # 安装依赖
   poetry add fastapi
   ...
   
   # poetry install          # 创建虚拟环境并安装依赖
   # poetry build            # 打包 wheel / sdist
   

2.2、Hatch（官方推荐的新一代工具）

1. 安装

   pipx install hatch
   

2. 生成项目模板

   hatch new mypkg
   

   会得到：

   mypkg/
     ├─ src/mypkg/__init__.py
     ├─ tests/
     └─ pyproject.toml      ← 已写好 build-system + project 字段
   

3. 依赖管理

   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本身不会自动卸载。

拓展举例

1. 安装并试用（不会记录依赖文件）：

   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
   

2. 安装并记录到项目（推荐团队项目）：

   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 对比

5、常见问题与注意事项

1. 环境隔离：
   • uvx 默认在临时环境中运行工具，与项目依赖隔离。若需访问项目依赖（如运行 pytest），应使用 uv run。
2. 缓存机制：
   • uv 缓存依赖以提高性能，可通过 uv cache clean 清理缓存。
3. 兼容性：
   • uv pip 命令兼容传统 pip 工作流，但部分高级功能可能略有差异。

五、参考文献：

1. 使用 uv 管理 Python 環境