Windows/Mac/Linux 永久配置 Python pip 国内镜像源教程

在默认情况下，Python 的包管理工具 pip 会直接连接位于境外的 Python Package Index（PyPI）官方服务器下载依赖包。由于跨国网络链路长、波动频繁，经常会出现下载速率仅有每秒数十千字节甚至直接触发 ReadTimeoutError 的情况。永久配置国内镜像源，就是让 pip 默认直接向清华大学、阿里云或腾讯云等国内同步镜像站请求数据，从而获得稳定、高速的依赖包安装体验。

一、国内镜像加速的底层机制与效果对比

国内镜像站点通过周期性定时同步官方 PyPI 的完整元数据与预编译 Wheel/源码包，建立位于国内骨干网与内容分发网络（CDN）节点的高速缓存。当开发者执行 pip install 时，客户端不再需要跨越国际公网路由，网络请求直接在本地或同城高速网络闭环响应。

二、推荐方案：使用 pip config 命令行一键永久配置

从 pip 10.0.0 版本开始，官方提供了内置的 pip config 子命令。这是全平台（Windows、macOS、Linux）最为稳妥、简洁的永久配置方式，因为用户无需关心各自操作系统具体的配置文件路径或目录权限，pip 会自动写入当前系统标准的用户配置路径中。

1. 执行写入命令

打开系统的命令行终端（Windows 用户使用 PowerShell 或 CMD，Mac/Linux 用户使用 Terminal），直接执行以下命令设置镜像源主地址：

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

如果选择其他国内镜像源，也可以直接替换后面的 URL 地址。同时，为了避免某些网络环境出现 SSL 证书提示，建议一并将主机名加入可信列表：

pip config set install.trusted-host pypi.tuna.tsinghua.edu.cn

2. 验证配置是否生效

配置完成后，在终端中输入以下命令查看已保存的配置项：

pip config list

正常情况下，终端会输出对应的键值对信息：

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

三、手动创建与修改配置文件（跨平台路径详解）

在某些受限环境或需要以自动化脚本初始化开发机时，直接新建或编辑配置文件是常见做法。不同操作系统下的文件名与默认读取目录不同，但配置文件的 INI 语法结构是完全一致的。

1. 配置文件通用语法结构

无论在哪个平台，文件的纯文本内容格式统一如下：

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

[install]
trusted-host = pypi.tuna.tsinghua.edu.cn

2. Windows 平台路径与操作

在 Windows 系统中，配置文件命名为 pip.ini，位于用户个人资料目录下。默认路径为：

C:\Users\<你的用户名>\AppData\Roaming\pip\pip.ini

也可以直接在文件资源管理器地址栏输入 %APPDATA%\pip 并回车。如果 pip 文件夹不存在，手动新建该文件夹，并在其内部新建名为 pip.ini 的文本文件，将上述内容粘贴保存即可。

3. macOS 平台路径与操作

在 macOS 系统中，配置文件命名为 pip.conf。按照 XDG 标准，现代 macOS 系统中优先存放在：

~/.config/pip/pip.conf

或 macOS 传统的 Application Support 路径 ~/Library/Application Support/pip/pip.conf。快速创建命令：

mkdir -p ~/.config/pip
cat << 'EOF' > ~/.config/pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

4. Linux 平台路径与操作

在 Linux 发行版（如 Ubuntu、Debian、CentOS、Fedora 等）中，配置文件同样命名为 pip.conf，首选路径与兼容路径如下：

• 首选路径：~/.config/pip/pip.conf
• 传统兼容路径：~/.pip/pip.conf

使用命令快速配置与 macOS 类似：

mkdir -p ~/.pip
cat << 'EOF' > ~/.pip/pip.conf
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

[install]
trusted-host = pypi.tuna.tsinghua.edu.cn
EOF

四、常用主流国内镜像源对比与选择

国内各大高校与头部云厂商均提供稳定的开源软件镜像服务。建议根据自身所在网络类型（教育网、特定云服务器厂商内网、或普通公网宽带）选择就近服务：

五、常见问题排查与注意事项

1. 虚拟环境（venv / conda）中的生效逻辑

用户级配置（如上述修改的 ~/.config/pip/pip.conf 或 %APPDATA%\pip\pip.ini）在激活标准 python -m venv 虚拟环境后依然全局默认生效。但如果虚拟环境自身根目录下存在 pip.conf，其优先级会高于用户全局配置。若排查时发现新环境未走国内源，可使用 pip config debug 打印出当前配置文件的加载层级和覆写顺序。

2. SSL 证书校验失败或不受信任报错

在企业代理网络或部分旧版 Python 环境中，可能会抛出 SSL: CERTIFICATE_VERIFY_FAILED 提示。除了确保系统根证书完整外，一定要在配置中加入 trusted-host 声明。例如使用阿里云时：

pip config set install.trusted-host mirrors.aliyun.com

3. 如何快速验证当前实际下载节点

配置后可以通过添加 -v（详细输出）参数安装一个轻量包进行实测：

pip install requests -v

在滚动的输出日志中，直接观察形如 Looking in indexes: https://pypi.tuna.tsinghua.edu.cn/simple 的行，若 URL 显示为你设置的国内镜像站，即表明永久换源已彻底生效。