pip 实用指南：包管理、镜像配置与 Docker 构建

pip 是 Python 官方推荐的包安装工具。为避免系统中存在多个 Python 解释器时安装到错误环境，本文统一使用：

python -m pip <command>

如果系统只提供 python3 命令，请将下文的 python 替换为 python3。

使用前先确认环境

查看 Python 和 pip 版本

python --version
python -m pip --version

第二条命令会同时显示 pip 版本、安装位置和对应的 Python 版本。安装结果与预期不符时，应先检查这里。

创建虚拟环境

不同项目可能依赖不同版本的包，建议在虚拟环境中安装依赖，避免污染系统 Python。

python -m venv .venv

Windows PowerShell：

.\.venv\Scripts\Activate.ps1

macOS 或 Linux：

source .venv/bin/activate

激活后再次运行 python -m pip --version，确认路径位于 .venv 中。

查询包和环境信息

查看已安装的包

python -m pip list

查看包的详细信息

python -m pip show package-name

输出包括版本、安装位置、依赖和被哪些包依赖等信息。

检查可升级的包

python -m pip list --outdated

检查依赖是否兼容

python -m pip check

如果已安装包缺少依赖或版本冲突，该命令会给出提示。

安装和卸载包

安装最新版本

python -m pip install package-name

安装指定版本或版本范围

python -m pip install "package-name==1.2.3"
python -m pip install "package-name>=1.2,<2.0"
python -m pip install "package-name~=1.2"

常用版本操作符：

==：精确匹配版本。
>=、<=：大于等于、小于等于。
>、<：大于、小于。
~=：兼容版本，例如 ~=1.2。
!=：排除指定版本。

包含 < 或 > 的版本表达式建议加引号，避免被命令行解释为重定向符号。

从本地目录或文件安装

python -m pip install .
python -m pip install -e .
python -m pip install ./dist/package_name-1.2.3-py3-none-any.whl

-e 表示以可编辑模式安装，适合本地开发 Python 项目。

卸载包

python -m pip uninstall package-name

升级和重新安装

升级 pip

python -m pip install --upgrade pip

升级指定包

python -m pip install --upgrade package-name

强制重新安装

python -m pip install --force-reinstall package-name

--ignore-installed 会忽略当前安装状态并直接覆盖文件，可能破坏由系统包管理器维护的环境。普通重装应使用 --force-reinstall。

使用 requirements.txt 管理依赖

从文件安装依赖

python -m pip install -r requirements.txt

导出当前环境中的包

python -m pip freeze > requirements.txt

pip freeze 会导出当前环境中的直接依赖和间接依赖。提交文件前应确认环境中没有混入与项目无关的包；不同操作系统生成的依赖也可能存在差异。

安装完成后可运行以下命令检查依赖关系：

python -m pip check

在 Docker 镜像中安装 Python 依赖

基础 Dockerfile

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN python -m pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "app.py"]

先复制 requirements.txt 并安装依赖，再复制应用代码，可以充分利用 Docker 的构建缓存。只有依赖文件发生变化时，pip 安装层才需要重新执行。

构建并运行镜像：

docker build -t my-python-app:latest .
docker run --rm my-python-app:latest

--no-cache-dir 可以避免将 pip 下载缓存写入镜像层，从而减小最终镜像体积。单一用途的容器通常不需要额外创建虚拟环境，因为容器本身已经提供了环境隔离。

使用多阶段构建

如果依赖需要编译，可以先在构建阶段生成 wheel，再将结果安装到运行阶段：

FROM python:3.12-slim AS builder

WORKDIR /build
COPY requirements.txt .
RUN python -m pip wheel --no-cache-dir --wheel-dir /wheels -r requirements.txt

FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
COPY --from=builder /wheels /wheels
RUN python -m pip install --no-cache-dir --no-index \
    --find-links=/wheels -r requirements.txt \
    && rm -rf /wheels

COPY . .

CMD ["python", "app.py"]

多阶段构建可以避免把编译工具留在最终镜像中。某些 Python 包仍依赖操作系统动态库，需要在运行阶段单独安装对应的系统包。

使用私有软件源

不要把私有源的用户名、密码或访问令牌写入 Dockerfile、ENV 或构建参数，否则凭据可能进入镜像历史和构建记录。启用 BuildKit 后，可以通过 secret 临时挂载 pip 配置：

# syntax=docker/dockerfile:1
RUN --mount=type=secret,id=pip_config,target=/etc/pip.conf \
    python -m pip install --no-cache-dir -r requirements.txt

docker build --secret id=pip_config,src=pip.conf \
    -t my-python-app:latest .

secret 只在对应构建步骤中可用，不会被复制到最终镜像层。

Docker 构建建议

在生产项目中固定关键依赖版本，减少不可预期的构建变化。
将 .venv、__pycache__、.git 等目录加入 .dockerignore。
优先使用 --no-cache-dir，避免把不需要的 pip 下载缓存写入镜像层。
最终容器尽量使用非 root 用户运行应用。
构建完成后运行 python -m pip check 或应用测试，验证依赖完整性。

配置软件源

临时指定镜像源

python -m pip install package-name --index-url https://pypi.tuna.tsinghua.edu.cn/simple

永久设置镜像源

python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

查看和恢复配置

python -m pip config list
python -m pip config unset global.index-url

常用 HTTPS 软件源：

PyPI 官方：https://pypi.org/simple
清华大学：https://pypi.tuna.tsinghua.edu.cn/simple
阿里云：https://mirrors.aliyun.com/pypi/simple/

优先选择可信且支持 HTTPS 的软件源。正常的 HTTPS 镜像无需添加 --trusted-host；该参数会放宽主机信任检查，仅应在明确了解风险时使用。

网络和缓存操作

延长网络超时时间

python -m pip install package-name --timeout 60

网络较慢时可以适当增加超时时间，不建议依赖某个固定的默认值。

查看和清理缓存

python -m pip cache info
python -m pip cache purge

清理缓存会导致后续安装重新下载包，一般只在缓存损坏或需要释放空间时使用。

常见问题排查

包安装到了错误的 Python 环境

python -m pip --version

检查输出中的 Python 版本和安装路径，并确认虚拟环境已激活。

出现依赖冲突

python -m pip check
python -m pip list --outdated

先确认冲突的包和版本要求，再有针对性地调整版本，不建议无条件升级环境中的全部包。

Linux 提示 externally-managed-environment

这表示当前 Python 由操作系统管理。应创建虚拟环境后再安装依赖，不建议直接使用 sudo pip install 或绕过系统保护。

提示 No matching distribution found

检查以下项目：

包名和版本号是否正确。
当前 Python 版本是否受该包支持。
操作系统和 CPU 架构是否有可用的发行文件。
当前软件源是否同步了所需版本。

常用命令速查

查看 pip 及其环境：python -m pip --version
列出已安装包：python -m pip list
查看包信息：python -m pip show package-name
安装包：python -m pip install package-name
卸载包：python -m pip uninstall package-name
升级包：python -m pip install --upgrade package-name
查看可升级包：python -m pip list --outdated
从文件安装依赖：python -m pip install -r requirements.txt
导出当前环境：python -m pip freeze > requirements.txt
检查依赖冲突：python -m pip check
查看 pip 配置：python -m pip config list
Docker 中安装依赖：python -m pip install --no-cache-dir -r requirements.txt

新文大师的藏经阁