pip 全局配置：代理和镜像源设置

在 Python 开发中，经常需要配置 pip 的代理和镜像源来加速包下载。通过配置 ~/.config/pip/pip.conf 文件，可以实现全局的 pip 配置，避免每次都要手动指定参数。

配置文件位置

Linux/macOS


~/.config/pip/pip.conf

Windows


%APPDATA%\pip\pip.ini

创建配置文件

首先创建配置目录和文件：


# 创建配置目录
mkdir -p ~/.config/pip
 
# 创建配置文件
touch ~/.config/pip/pip.conf

基本配置结构


[global]
# 全局配置选项
 
[install]
# 安装相关配置
 
[download]
# 下载相关配置

镜像源配置

国内常用镜像源

清华大学镜像源（推荐）


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

阿里云镜像源


[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
trusted-host = mirrors.aliyun.com

中科大镜像源


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

豆瓣镜像源


[global]
index-url = https://pypi.douban.com/simple/
trusted-host = pypi.douban.com

华为云镜像源


[global]
index-url = https://repo.huaweicloud.com/repository/pypi/simple/
trusted-host = repo.huaweicloud.com

多镜像源配置

可以配置多个镜像源，pip 会自动尝试：


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

代理配置

HTTP/HTTPS 代理


[global]
proxy = http://proxy.example.com:8080

带认证的代理


[global]
proxy = http://username:password@proxy.example.com:8080

SOCKS 代理


[global]
proxy = socks5://127.0.0.1:1080

分别配置不同协议的代理


[global]
proxy = http://proxy.example.com:8080
[install]
proxy = http://proxy.example.com:8080
[download]
proxy = http://proxy.example.com:8080

完整配置示例

国内用户推荐配置


[global]
# 使用清华大学镜像源
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
 
# 备用镜像源
extra-index-url = 
    https://mirrors.aliyun.com/pypi/simple/
    https://pypi.mirrors.ustc.edu.cn/simple/
 
# 超时设置
timeout = 60
retries = 3
 
# 缓存设置
cache-dir = ~/.cache/pip

企业内网用户配置


[global]
# 内网镜像源
index-url = http://internal-pypi.company.com/simple/
trusted-host = internal-pypi.company.com
 
# 代理设置
proxy = http://proxy.company.com:8080
 
# 超时和重试
timeout = 120
retries = 5
 
# 缓存目录
cache-dir = ~/.cache/pip

开发环境配置


[global]
# 镜像源
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
 
# 代理（如果需要）
# proxy = http://127.0.0.1:7890
 
# 安装配置
[install]
# 升级策略
upgrade-strategy = only-if-needed
 
# 用户安装
user = false
 
# 编译选项
[build]
# 编译超时
timeout = 300
 
# 下载配置
[download]
# 下载超时
timeout = 60

高级配置选项

缓存和临时目录


[global]
# 缓存目录
cache-dir = ~/.cache/pip
 
# 临时目录
temp-dir = /tmp/pip-temp
 
# 构建目录
build-dir = ~/.cache/pip-build

网络配置


[global]
# 超时设置（秒）
timeout = 60
 
# 重试次数
retries = 3
 
# 连接池大小
max-connections = 5
 
# 禁用 SSL 验证（不推荐）
# cert = /path/to/cert.pem

安装选项


[install]
# 升级策略
upgrade-strategy = only-if-needed
 
# 用户安装
user = false
 
# 不依赖项
no-deps = false
 
# 预发布版本
pre = false
 
# 强制重新安装
force-reinstall = false

环境变量配置

除了配置文件，也可以通过环境变量设置：


# 镜像源
export PIP_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
export PIP_TRUSTED_HOST="pypi.tuna.tsinghua.edu.cn"
 
# 代理
export PIP_PROXY="http://proxy.example.com:8080"
 
# 超时
export PIP_TIMEOUT="60"
 
# 重试次数
export PIP_RETRIES="3"

验证配置

检查当前配置


# 查看 pip 配置
pip config list
 
# 查看全局配置
pip config list --global
 
# 查看用户配置
pip config list --user

测试镜像源


# 测试安装包
pip install --dry-run requests
 
# 查看包信息
pip show pip
 
# 列出已安装包
pip list

测试代理


# 测试网络连接
curl -I https://pypi.org/simple/
 
# 通过代理测试
curl -I --proxy http://proxy.example.com:8080 https://pypi.org/simple/

常见问题解决

1. SSL 证书问题


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

2. 超时问题


[global]
timeout = 120
retries = 5

3. 权限问题


# 使用用户安装
pip install --user package_name
 
# 或配置文件中设置
[install]
user = true

4. 代理认证问题


[global]
proxy = http://username:password@proxy.example.com:8080

5. 镜像源切换


# 临时使用不同镜像源
pip install -i https://mirrors.aliyun.com/pypi/simple/ package_name
 
# 临时禁用代理
pip install --proxy "" package_name

最佳实践

1. 配置文件管理


# 备份配置文件
cp ~/.config/pip/pip.conf ~/.config/pip/pip.conf.backup
 
# 版本控制（可选）
git add ~/.config/pip/pip.conf

2. 多环境配置


# 开发环境
export PIP_CONFIG_FILE=~/.config/pip/pip-dev.conf
 
# 生产环境
export PIP_CONFIG_FILE=~/.config/pip/pip-prod.conf

3. 团队配置

创建团队共享的配置文件：


# .piprc (项目根目录)
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
timeout = 60
retries = 3

4. 自动化脚本


#!/bin/bash
# setup-pip-config.sh
 
# 创建配置目录
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
timeout = 60
retries = 3
cache-dir = ~/.cache/pip
EOF
 
echo "pip 配置完成！"

总结

通过配置 ~/.config/pip/pip.conf 文件，可以：

加速包下载：使用国内镜像源
解决网络问题：配置代理服务器
提高稳定性：设置超时和重试
统一环境：团队共享配置

合理配置 pip 可以显著提升 Python 开发体验，特别是在网络环境受限的情况下。建议根据实际网络环境选择合适的镜像源和代理配置。