Python：包管理（pip / uv / poetry）

目录

• 1. 安装 pip / uv / poetry
  • 1.1 装 pip
  • 1.2 装 uv（推荐）
  • 1.3 装 poetry
• 2. 虚拟环境（强烈建议）
  • 用 venv（标准库）
  • 用 uv（速度飞快）
  • 用 poetry
• 3. 装包 / 卸包
• 4. 镜像源配置
  • 4.1 临时使用
  • 4.2 永久配置（推荐）
  • 常用国内镜像
• 5. 依赖锁定与可复现
  • pip + pip-tools（传统方式）
  • uv（现代方式）
  • poetry
  • 导出 requirements.txt（对接 Docker 等场景）
• 6. 安装命令行工具：pipx
• 7. 日常命令速查
• 8. 常见问题

---

Python 的包管理生态近两年变化很大：uv 速度极快、
并能替代 pip / venv / pip-tools；poetry 仍是
成熟的依赖管理工具；pip 本身是必须掌握的基础。

工具	作用	速度	推荐度
pip	装包、卸包、依赖锁定	中	★★★
uv	pip + venv + lock + 项目管理一体化	极快	★★★★
poetry	依赖 + 虚拟环境 + 打包	快	★★★
pipx	在隔离环境安装 命令行工具	快	★★★
conda	跨平台 + 非 Python 依赖	慢	★★

⚠️ easy_install 已 废弃，请使用 pip 或 uv。Python 3.12 起 python
命令能自动识别 pip，但 Windows 上仍需先 py -m ensurepip。

---

1. 安装 pip / uv / poetry

1.1 装 pip

较新的 Python（≥ 3.11）通常自带 pip，可用 python -m pip --version 验证。

# Linux / macOS：通常 python3 自带 pip
python3 -m ensurepip --upgrade
# Windows：
py -m ensurepip --upgrade

如果你必须从零装 pip：

curl -sSL https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py

1.2 装 uv（推荐）

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

# Windows
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或者直接用 pip
pip install -U uv

1.3 装 poetry

pip install -U poetry
# 或官方推荐：pipx install poetry

---

2. 虚拟环境（强烈建议）

永远不要 直接把包装到系统 Python。

用 venv（标准库）

python3 -m venv .venv
source .venv/bin/activate          # macOS / Linux
.venv\Scripts\Activate.ps1         # Windows PowerShell
deactivate                         # 退出

用 uv（速度飞快）

uv venv .venv                      # 创建
source .venv/bin/activate
uv pip install flask requests      # 在 venv 中装包

用 poetry

poetry new myapp
cd myapp
poetry env use 3.12
poetry add flask requests
poetry shell

---

3. 装包 / 卸包

# pip
pip install requests
pip install "requests==2.32.3"     # 指定版本
pip install -U requests            # 升级
pip uninstall requests

# uv（兼容 pip 命令，但快 10~100x）
uv pip install requests
uv pip install -r requirements.txt
uv pip sync requirements.txt       # 用 lock 文件精确同步

# poetry
poetry add requests
poetry add "requests==2.32.3"
poetry remove requests
poetry update

---

4. 镜像源配置

4.1 临时使用

pip install requests \
  -i https://pypi.tuna.tsinghua.edu.cn/simple

4.2 永久配置（推荐）

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn
# 写到了 ~/.config/pip/pip.conf（macOS/Linux）
# 或 %APPDATA%\pip\pip.ini（Windows）

uv 的镜像配置：

export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
# 或写到 ~/.config/uv/uv.toml

常用国内镜像

镜像	URL
清华 TUNA	https://pypi.tuna.tsinghua.edu.cn/simple
阿里云	https://mirrors.aliyun.com/pypi/simple
中科大	https://pypi.mirrors.ustc.edu.cn/simple
腾讯	https://mirrors.cloud.tencent.com/pypi/simple

---

5. 依赖锁定与可复现

只写 requests 不够，需要 锁定版本 才能保证别人安装时跟你完全一致。

pip + pip-tools（传统方式）

pip install -U pip-tools
# requirements.in 里写：requests
pip-compile requirements.in          # 生成 requirements.txt
pip-sync requirements.txt            # 把环境同步成文件里的版本

uv（现代方式）

# uv add 会自动写 pyproject.toml + 更新 uv.lock
uv add requests
uv sync                              # 同事克隆项目后一次同步

poetry

poetry add requests                   # 自动写 pyproject.toml + poetry.lock
poetry install                        # 别人克隆后一次同步

导出 requirements.txt（对接 Docker 等场景）

# poetry
poetry export -f requirements.txt --output requirements.txt --without-hashes

# uv
uv pip freeze > requirements.txt

---

6. 安装命令行工具：pipx

像 black、ruff、poetry、httpie 这类 全局命令行工具，推荐用
pipx，它会为每个工具建独立环境，避免污染全局。

pip install -U pipx
pipx ensurepath                       # 把 ~/.local/bin 加到 PATH

pipx install black
pipx install ruff
pipx install poetry
pipx list
pipx upgrade-all

---

7. 日常命令速查

# 查看 / 搜索
pip list
pip list --outdated
pip show requests
pip search xxx       # pip 21.2+ 已移除搜索功能，改用 pypi.org 站内搜索

# 导出依赖
pip freeze > requirements.txt

# 重装
pip install --force-reinstall requests

# 只下载不安装（适合做本地镜像）
pip download -d ./pkgs requests

---

8. 常见问题

• pip 命令找不到？ 用 python -m pip ... 代替，或确认已 python -m ensurepip。
• 安装时编译失败（_sqlite3、cryptography）？
  • macOS：xcode-select --install
  • Linux：sudo apt install build-essential libffi-dev libssl-dev python3-dev
• 「No module named xxx」但已经装过？ 99% 是 多个 Python / venv 串台。
  用 which python 和 which pip 确认。
• SSL: CERTIFICATE_VERIFY_FAILED？ 升级 pip / certifi，或临时加
  --trusted-host pypi.org（不推荐生产用）。
• 老项目用 requirements.txt，新项目怎么办？ 优先用 pyproject.toml +
  uv / poetry。requirements.txt 留作给 Docker / CI 同步即可。
• 公司内网 PyPI？ 配 index-url 指向内部源；uv 同样支持。