Ubuntu / WSL 安装pipx

一、安装pipx

在 Ubuntu / WSL 上可以用两种方式安装，推荐第二种（官方脚本）或第三种（pip 安装最新版本并自动配置 PATH）。

1. apt 安装（最快，但版本往往偏旧）

sudo apt update
sudo apt install pipx
# apt 默认把可执行文件装在 /usr/bin/pipx

如果只是想临时体验可以这么做，但通常 apt 源里的 pipx 版本落后，且不会帮你配置用户路径。

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
  

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

1. 通过独立脚本安装（推荐）：

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh# Windows（PowerShell）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 通过 pipx 安装：

pipx install uv

3. 验证安装：

uv --version

---

3.2、uv 核心功能与命令

# Create a new directory for our project
uv init weather
cd weather# Create virtual environment and activate it
uv venv
source .venv/bin/activate# Install dependencies
uv add "mcp[cli]" httpx# Create our server file
touch weather.py

1. 虚拟环境管理

• 创建虚拟环境：

  uv venv           # 默认创建 .venv 目录
  uv venv --python 3.11  # 指定 Python 版本
  

• 删除虚拟环境：

  uv venv --remove .venv
  

2. 依赖管理

• 安装包：

  uv pip install requests         # 安装单个包
  uv pip install -r requirements.txt  # 批量安装
  

• 同步依赖：

  uv sync  # 根据 pyproject.toml 或 requirements.txt 同步环境
  

• 依赖锁定：

  uv pip compile requirements.in -o requirements.txt  # 生成锁定文件
  uv pip sync requirements.txt  # 同步环境至锁定状态
  

3. 项目管理

• 初始化项目：

  uv init myproject  # 生成 pyproject.toml 和 .python-version
  

• 添加/移除依赖：

  uv add flask        # 添加生产依赖
  uv add --dev pytest # 添加开发依赖
  uv remove fastapi   # 移除依赖
  

4. Python 版本管理

• 安装 Python：

  uv python install 3.11  # 安装指定版本
  

• 查看已安装版本：

  uv python list
  

---

四、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  # 升级

---

3.3、uv 与 uvx 对比

场景	uv 命令	uvx 命令
运行临时工具	uv tool run <工具名>	uvx <工具名>
指定工具版本	uv tool run tool@版本	uvx tool@版本
全局安装工具	uv tool install	不适用
包含额外依赖	uv tool run --with	uvx --with

---

3.4、常见问题与注意事项

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