Python pip 完整配置指南

李昊哲-小课

726人浏览 · 2026-04-19 07:51:34

李昊哲-小课 · 2026-04-19 07:51:34 发布

Python pip 完整配置指南

涵盖系统初始化、虚拟环境、镜像源配置、缓存管理四大核心主题，适用于 Windows / macOS / Linux 全平台。

Python pip

一、系统初始化与 Python 安装

以下步骤适用于全新安装的 Ubuntu / Debian 服务器，建议在配置 Python 环境前依次完成。

1.1 设置系统时区

sudo timedatectl set-timezone Asia/Shanghai

验证时区设置：

timedatectl

1.2 系统环境升级

sudo apt update && sudo apt -y dist-upgrade

1.3 安装 Python3、pip 与 venv

sudo apt -y install python3 python3-pip python3-venv

说明：python3-venv 用于创建 Python 虚拟环境，Ubuntu 24.04+ 必须安装（详见第二章）。

1.4 升级 pip

python3 -m pip install --upgrade pip

提示：建议使用 python3 -m pip 而非直接调用 pip3，可避免路径混乱问题。

二、PEP 668 与虚拟环境

重要：Ubuntu 24.04 及后续版本引入了 PEP 668 保护机制，禁止在系统层面使用 pip 安装包。在配置 pip 之前，必须先了解虚拟环境的使用方式。

2.1 什么是 PEP 668

PEP 668 是 Python 官方提案，旨在防止用户通过 pip 安装的包与系统包管理器（apt）管理的 Python 包产生冲突。直接运行 pip install 会报错：

error: externally-managed-environment
× This environment is externally managed

2.2 创建与使用虚拟环境

创建虚拟环境（在项目目录下执行）：

python3 -m venv myenv

激活虚拟环境：

source myenv/bin/activate

激活后，终端提示符前会出现 (myenv) 前缀，此时即可正常使用 pip 安装包：

pip install numpy

退出虚拟环境：

deactivate

2.3 虚拟环境中的配置继承

虚拟环境激活后，pip 配置仍遵循全局配置文件（pip.ini / pip.conf）中的镜像源和缓存目录设置，无需重复配置。

如需为特定项目单独配置，可在项目目录下创建 pip.conf 文件，或激活虚拟环境后使用 pip config set 命令。

三、pip 国内镜像源配置

由于 PyPI 官方源服务器位于海外，国内访问速度较慢，建议配置国内镜像源加速下载。

3.1 常用国内镜像源

名称	地址
Python 官方	`https://pypi.python.org/simple/`
清华大学	`https://pypi.tuna.tsinghua.edu.cn/simple/`
阿里云	`https://mirrors.aliyun.com/pypi/simple/`
中国科学技术大学	`https://mirrors.ustc.edu.cn/pypi/simple/`

3.2 临时使用

安装时通过 -i 参数指定镜像源，仅对当前命令生效：

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

3.3 全局设置

方式一：命令行设置

通过 pip config set 永久修改全局镜像源：

清华大学源（推荐）：

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

阿里云源（备选）：

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple

方式二：配置文件设置（推荐）

为防止单一镜像失效，建议在配置文件中设置多个镜像源作为回退。

Windows — 配置文件路径：%APPDATA%\pip\pip.ini（如 C:\Users\用户名\AppData\Roaming\pip\pip.ini）

macOS / Linux — 配置文件路径：~/.config/pip/pip.conf（或 ~/.pip/pip.conf）

配置内容相同：

[global]
timeout = 30
index-url = https://pypi.tuna.tsinghua.edu.cn/simple/
extra-index-url =
        https://mirrors.aliyun.com/pypi/simple/
        https://mirrors.ustc.edu.cn/pypi/simple/

[install]
trusted-host =
        pypi.tuna.tsinghua.edu.cn
        mirrors.aliyun.com
        mirrors.ustc.edu.cn

3.4 查看与调试配置

查看当前配置：

pip config list

调试配置优先级（配置不生效时使用）：

pip config debug

优先级顺序：虚拟环境 > 用户级 > 系统级

四、pip 缓存管理

pip 会将下载的包缓存到本地，重复安装时可直接使用缓存以加速安装。但缓存可能占用大量磁盘空间，需要定期管理。

4.1 默认缓存路径

平台	默认路径
Windows	`%LocalAppData%\pip\Cache`（如 `C:\Users\用户名\AppData\Local\pip\Cache`）
macOS	`~/Library/Caches/pip`
Linux	`~/.cache/pip`（尊重 `XDG_CACHE_HOME` 环境变量）

4.2 缓存管理命令

命令	作用
`pip cache dir`	查看缓存根目录
`pip cache info`	查看缓存统计（大小、各目录路径）
`pip cache list [pattern]`	列出缓存包，支持通配符（如 `pip cache list numpy*`）
`pip cache remove <包名>`	删除单个包缓存（如 `pip cache remove requests`）
`pip cache purge`	清空所有缓存（轮子缓存 + HTTP 缓存，谨慎使用）

4.3 修改缓存位置

方式一：配置文件（推荐，永久生效）

在 pip 配置文件 [global] 段中添加 cache-dir 选项：

Windows（%APPDATA%\pip\pip.ini）：

[global]
cache-dir = D:\Python\pip_cache

macOS / Linux（~/.config/pip/pip.conf）：

[global]
cache-dir = /home/用户名/.cache/pip

方式二：命令行永久指定

pip config set global.cache-dir D:\pip_cache

方式三：环境变量

平台	临时生效	永久生效
Windows	`set PIP_CACHE_DIR=D:\Python\pip_cache`	系统环境变量新建 `PIP_CACHE_DIR`
macOS / Linux	`export PIP_CACHE_DIR=/path/to/cache`	写入 `~/.bashrc` 或 `~/.zshrc`

macOS / Linux 永久生效：

echo 'export PIP_CACHE_DIR=/path/to/cache' >> ~/.bashrc
source ~/.bashrc

方式四：命令行临时指定

仅当前命令有效：

pip install 包名 --cache-dir /自定义/路径

4.4 临时禁用缓存

安装时加 --no-cache-dir 参数（不推荐长期禁用）：

pip install 包名 --no-cache-dir

4.5 验证与排查

验证缓存配置：

pip cache dir

输出路径为自定义路径则配置成功。安装一个包后，检查自定义目录是否生成文件即可确认。

常见问题排查：

问题	排查方法
配置不生效	执行 `pip config debug` 检查优先级；确认虚拟环境是否覆盖了用户级配置
缓存仍占用原磁盘	检查是否同时配置了环境变量和配置文件（配置文件优先级更高）；确认 pip 版本 ≥ 20.1
空间占用过大	定期执行 `pip cache purge` 清理，或将缓存目录配置到大容量磁盘
缓存损坏	使用 `pip cache remove <包名>` 删除特定包缓存，比全清更安全

五、综合配置示例

以下是一个同时配置镜像源和缓存目录的完整示例，可作为日常使用的标准配置模板。

Windows（`%APPDATA%\pip\pip.ini`）

[global]
timeout = 30
index-url = https://pypi.tuna.tsinghua.edu.cn/simple/
extra-index-url =
        https://mirrors.aliyun.com/pypi/simple/
        https://mirrors.ustc.edu.cn/pypi/simple/
cache-dir = D:\Python\pip_cache

[install]
trusted-host =
        pypi.tuna.tsinghua.edu.cn
        mirrors.aliyun.com
        mirrors.ustc.edu.cn

macOS / Linux（`~/.config/pip/pip.conf`）

[global]
timeout = 30
index-url = https://pypi.tuna.tsinghua.edu.cn/simple/
extra-index-url =
        https://mirrors.aliyun.com/pypi/simple/
        https://mirrors.ustc.edu.cn/pypi/simple/
cache-dir = ~/.cache/pip

[install]
trusted-host =
        pypi.tuna.tsinghua.edu.cn
        mirrors.aliyun.com
        mirrors.ustc.edu.cn