pip 用户使用手册

Python 包管理工具 · 从入门到日常排障

1. pip 简介

pip 是 Python 的标准包管理工具，用于安装、卸载、管理 Python 第三方库。Python 3.4+ 自带 pip（ensurepip），通常无需单独安装。

# 查看版本
pip --version

# 升级 pip 自身
pip install --upgrade pip

2. 包安装

2.1 从 PyPI 安装

# 安装最新版本
pip install requests

# 安装指定版本
pip install requests==2.31.0

# 版本约束（兼容）
pip install "requests>=2.25,<3.0"
pip install requests~=2.31.0    # >=2.31.0, <2.32.0

# 安装多个包
pip install requests flask numpy

# 不安装依赖
pip install requests --no-deps

2.2 从其他源安装

# 从 GitHub 安装
pip install git+https://github.com/psf/requests.git
pip install git+https://github.com/psf/requests.git@v2.31.0

# 从本地文件安装
pip install /path/to/package.tar.gz
pip install /path/to/package.whl
pip install -e /path/to/local/package   # 开发模式（editable）
pip install -e .                            # 安装当前目录的包（开发模式）

# 从本地目录安装（含 setup.py / pyproject.toml）
pip install ./my-package

2.3 可编辑安装 `pip install -e`

pip install -e .（editable / develop mode）将当前目录以"可编辑模式"安装到 Python 环境。与普通安装不同，它不是复制文件到 site-packages/，而是创建一个指向源码目录的链接。

# 安装当前目录
cd my-project
pip install -e .

# 等价写法
pip install --editable .

工作原理：

在 site-packages/ 下写入一个 .egg-link 文件，内容是源码目录的绝对路径
Python import 时通过 .egg-link 找到源码目录，直接读取
源码改了立即生效，无需重新安装

CLI 入口点（pyproject.toml）：

# pyproject.toml
[project.scripts]
my-cli = "my_package.cli:main"

pip install -e . 会根据 [project.scripts] 在 PATH 中生成可执行脚本（如 my-cli），这些脚本指向 site-packages/ 中的包装器，最终调用源码中的 main() 函数。修改源码，命令行为立即生效。

典型场景：

本地开发 CLI 工具：安装后直接敲命令调试，改代码即时生效
monorepo 项目：多个子包互相依赖时，用 -e 安装避免反复 install
源码阅读：安装后可 import 并在源码中加 breakpoint() 调试

注意：pip install -e . 需要项目根目录有 pyproject.toml 或 setup.py。如果只是普通脚本目录没有打包配置，则无法使用。

3. 包卸载

# 卸载
pip uninstall requests

# 跳过确认提示
pip uninstall -y requests

# 批量卸载
pip uninstall -y -r requirements.txt

4. 包信息查看

# 列出已安装的包
pip list

# 列出过时的包（可升级的）
pip list --outdated

# 查看指定包信息
pip show requests

# 查看包的所有文件位置
pip show -f requests

# 冻结当前环境（生成精确版本列表）
pip freeze
pip freeze > requirements.txt

5. requirements.txt 依赖管理

5.1 常用格式

# requirements.txt 示例
requests==2.31.0
flask>=2.3,<3.0
numpy
git+https://github.com/user/repo.git@v1.0.0
./local-package

5.2 常用操作

# 从文件安装
pip install -r requirements.txt

# 生成 requirements.txt（精确版本）
pip freeze > requirements.txt

# 安装后验证依赖完整性
pip check

# 分析依赖树
pip install pipdeptree && pipdeptree

6. 镜像源配置

6.1 国内常用镜像

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

6.2 临时使用

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

6.3 永久配置

Linux / macOS：~/.pip/pip.conf

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

Windows：%APPDATA%\pip\pip.ini

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

7. 虚拟环境

7.1 venv（Python 内置）

# 创建
python -m venv myenv

# 激活
source myenv/bin/activate      # Linux / macOS
myenv\Scripts\activate         # Windows

# 退出
deactivate

# 删除
rm -rf myenv

7.2 virtualenv（需安装）

pip install virtualenv
virtualenv myenv

# 指定 Python 版本
virtualenv -p /usr/bin/python3.11 myenv

7.3 conda（Anaconda / Miniconda）

conda create -n myenv python=3.11
conda activate myenv
conda deactivate

8. 缓存管理

# 查看缓存目录
pip cache dir

# 查看缓存信息
pip cache info

# 列出缓存的包
pip cache list

# 清理所有缓存
pip cache purge

# 删除指定包缓存
pip cache remove requests

# 安装时不使用缓存
pip install --no-cache-dir requests

9. 高级用法

9.1 下载而不安装

# 下载包及其依赖到本地
pip download requests -d ./packages

# 离线安装
pip install --no-index --find-links=./packages requests

9.2 约束文件（constraints）

约束文件限制版本但不自动安装，与 requirements.txt 配合使用：

# constraints.txt
requests>=2.25

# 使用约束安装
pip install -r requirements.txt -c constraints.txt

9.3 用户级安装（无需 sudo）

pip install --user requests
# 安装在 ~/.local/lib/pythonX.Y/site-packages/

9.4 列出依赖树

# 查看某包的依赖
pip show requests

# 更清晰的依赖树
pip install pipdeptree
pipdeptree -p requests        # 只看 requests 及其依赖
pipdeptree -r                 # 反向依赖（谁依赖了它）

9.5 编译 wheel

# 从源码编译 wheel
pip wheel requests

# 指定输出目录
pip wheel -w ./wheels requests

9.6 安全审计

# 检查已知漏洞（需安装 pip-audit）
pip install pip-audit
pip-audit

10. 常见问题

10.1 SSL 证书错误

# 临时跳过（不推荐）
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org requests

# 永久：在 pip.conf 添加
[global]
trusted-host = pypi.org
               files.pythonhosted.org

10.2 权限不足（Permission denied）

# 方案1：用户级安装
pip install --user requests

# 方案2：使用虚拟环境
python -m venv myenv && source myenv/bin/activate

10.3 依赖冲突

# 检查冲突
pip check

# 使用 pip-tools 管理精确依赖
pip install pip-tools
pip-compile requirements.in          # 生成已解析的 requirements.txt
pip-sync requirements.txt            # 同步环境到精确匹配

# 强制安装（忽略冲突，慎用）
pip install --force-reinstall requests

10.4 pip 自身损坏

# 重新安装 pip
python -m ensurepip --upgrade
# 或
python -m pip install --upgrade pip

10.5 指定平台 / 架构下载

# 下载非当前平台的包（如 macOS arm64 下载 Linux x86_64 包）
pip download --platform manylinux2014_x86_64 --only-binary=:all: requests -d ./linux-pkgs

10.6 已安装但 import 找不到

# 确认 pip 对应的 Python
pip --version                    # 查看 pip 所属的 Python
python -c "import sys; print(sys.executable)"
which python && which pip        # 确认一致

11. 常用配置项速查

pip.conf / pip.ini 完整配置项：

[global]
index-url = https://pypi.org/simple
extra-index-url = https://pypi.example.com/simple
trusted-host = pypi.example.com
timeout = 60
retries = 3
cache-dir = /path/to/cache
no-cache-dir = false

[install]
# 仅安装二进制 wheel，不回退到源码编译
only-binary = :all:

[list]
format = columns