Python pip永久配置国内镜像源(Windows/macOS/Linux)

pip 默认从 PyPI（pypi.org）下载包，服务器位于海外，国内直连经常遇到下载缓慢甚至超时中断的问题。解决办法是把 pip 的索引地址永久指向国内镜像站——配置一次之后，后续每次 pip install 都会自动走国内源，无需反复加 -i 参数。

本文按三个系统分别说明配置方法，同时介绍可用的镜像站点、验证方式和常见问题。

国内常用镜像站点

在动手配置之前，先确定要使用哪个镜像。下面几个站点同步频率高、长期稳定，任选其一即可：

清华源和阿里云源使用最广泛，本文示例以清华源为例。如果你所在地区访问某个镜像更快，替换 URL 即可，配置格式完全相同。

通用方法：用 pip config 命令一键配置（推荐）

pip 10.0 以上版本内置了 pip config 命令，可以直接在终端写入配置，不需要手动创建文件。这个方法在三个系统上通用。

打开终端（Windows 下使用 CMD 或 PowerShell），执行：

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

命令执行后会输出类似这样的提示，说明配置文件的写入位置：

# Windows 示例输出：
Writing to C:\Users\用户名\AppData\Roaming\pip\pip.ini

# macOS/Linux 示例输出：
Writing to /Users/用户名/.config/pip/pip.conf

如果同时需要设置 trusted-host（某些公司内网环境要求），追加一条命令：

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

手动编辑配置文件

如果你需要更精细的控制（比如同时配置多个选项），或者环境不支持 pip config，可以直接编辑配置文件。三个系统的配置文件路径不同，内容格式相同。

Windows

配置文件路径为 %APPDATA%\pip\pip.ini。在资源管理器地址栏输入 %APPDATA% 回车，如果没有 pip 文件夹就新建一个，在里面创建 pip.ini 文件（注意扩展名是 .ini，不是 .txt），写入以下内容：

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

完整路径通常是 C:\Users\你的用户名\AppData\Roaming\pip\pip.ini。

macOS

配置文件路径为 ~/.config/pip/pip.conf。打开终端，执行以下命令创建目录和文件：

mkdir -p ~/.config/pip

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

也可以用任何文本编辑器打开 ~/.config/pip/pip.conf 手动写入上面 [global] 段的内容。

Linux

Linux 的配置路径与 macOS 相同：~/.config/pip/pip.conf。部分旧文档提到 ~/.pip/pip.conf，这个路径也能识别，但推荐使用符合 XDG 规范的新路径。

mkdir -p ~/.config/pip

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

验证配置是否生效

配置完成后，用两种方式确认镜像源已经切换成功。

方法一：查看当前配置

pip config list

正确输出应包含你设置的镜像地址：

# 示例输出
global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'
global.trusted-host='pypi.tuna.tsinghua.edu.cn'

方法二：实际安装一个包

安装一个小型包来观察下载源是否已经变化：

pip install requests --upgrade

注意观察输出中的下载地址。如果显示类似 Downloading https://pypi.tuna.tsinghua.edu.cn/... 的内容，说明已经在使用国内镜像。同时你会明显感觉到下载速度比之前快得多。

如果输出中仍然显示 pypi.org，说明配置未生效，检查以下几点：

• 配置文件路径是否正确（注意 Windows 是 pip.ini，不是 pip.conf）
• 文件内容中 [global] 标题是否完整，拼写是否有误
• URL 末尾的 /simple 不能省略
• 是否存在多个 Python 环境，当前 pip 指向的是否是你配置的那个环境

虚拟环境中的镜像配置

如果你使用 venv 或 virtualenv 创建了虚拟环境，需要了解：全局配置（~/.config/pip/pip.conf 或 %APPDATA%\pip\pip.ini）对虚拟环境内的 pip 同样生效。也就是说，配置一次全局镜像，所有虚拟环境都会使用。

如果你需要给某个虚拟环境单独配置不同的镜像源，可以在虚拟环境目录下创建 pip.conf（或 Windows 下的 pip.ini）：

# Linux/macOS 虚拟环境
venv_dir/pip.conf

# Windows 虚拟环境
venv_dir\pip.ini

虚拟环境内的配置优先级高于全局配置。

conda 用户的补充说明

如果你同时使用 Anaconda 或 Miniconda，需要区分两件事：

• conda install 使用的是 conda 的 channel 配置，与 pip 无关，需要单独配置 .condarc 文件
• 在 conda 环境中执行 pip install 仍然使用 pip 的配置文件，上述方法同样适用

两者互不影响，分别配置即可。

临时使用镜像源（不修改配置）

如果只是偶尔需要使用镜像加速，不想修改全局配置，可以在安装命令中用 -i 参数临时指定：

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

这种方式只对当前这一次安装生效，不会改变任何配置文件。适合在别人的机器上临时使用，或者在配置镜像之前先测试某个镜像站的速度。

常见问题

配置后安装仍然很慢

先用 pip config list 确认配置已生效。如果配置正确但仍然慢，可能是当前镜像站节点负载较高。尝试换一个镜像站（比如从清华换到阿里云），操作方法相同，只需替换 URL。

出现 SSL 证书错误

某些企业内网或代理环境下，HTTPS 连接可能被中间人证书拦截，导致类似 SSLError 的报错。可以在配置文件中加入 trusted-host（前文已包含），或者检查公司网络是否需要额外安装根证书。

pip config set 报错 "No such command"

这说明 pip 版本低于 10.0。执行以下命令升级 pip：

# 使用临时镜像加速升级 pip 本身
pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple

升级完成后再执行 pip config set 命令。

多个 Python 版本共存时配置哪一个

全局配置文件对同一用户下所有 Python 版本的 pip 都生效，不需要分别配置。如果你通过 python3 -m pip 和 python -m pip 使用不同版本的 Python，只要它们属于同一个操作系统用户，共享同一份配置文件。