← 返回博客
RUENZHESARPTDEFRJAKOITTRIDVIFAHI

PyPI代理：如何通过pip在受限地区安装Python包

如果pip因您所在地区的PyPI封锁而无法下载软件包，本文将展示如何设置代理和镜像以确保顺利运行。

📅2026年7月20日
```html

PyPI是Python包的主要仓库，在一些国家和企业网络中会定期被封锁。如果pip install卡住或出现连接错误，问题正是出在这里。本文将讨论所有有效的方法：从环境变量到镜像和Docker容器。

为什么PyPI不可用：封锁原因

在配置代理之前，了解您遇到的具体封锁类型非常重要。这将影响解决方案的选择。

区域封锁

在一些国家（如伊朗、中国以及在制裁限制期间的俄罗斯某些地区），对pypi.org和files.pythonhosted.org的访问在提供商或国家防火墙层面被封锁。命令pip install requests会卡住或返回ConnectionError。

企业代理和防火墙

许多公司将所有出站流量通过企业代理服务器。如果pip不知道这个代理，它会尝试直接连接并被拒绝。此时的典型错误是：ProxyError: HTTPSConnectionPool(host='pypi.org', port=443)。

没有互联网访问的服务器（air-gapped）

生产服务器、银行服务器、政府机构或隔离的云VPC通常完全无法直接访问互联网。在这种情况下，需要在网络内部设置代理服务器或本地PyPI镜像。

临时故障和速率限制

有时PyPI会限制来自单个IP的请求数量，尤其是当您同时启动多个Docker容器时。在这种情况下，使用IP轮换的代理可以解决问题。

如何检查PyPI是否被封锁？

在终端中执行：curl -v https://pypi.org/simple/。如果连接卡住或返回SSL/timeout错误——您的IP无法访问PyPI。如果错误包含407 Proxy Authentication Required——您处于企业代理后面。

环境变量：最快的方法

最简单和通用的方法是设置标准环境变量HTTP_PROXY和HTTPS_PROXY。Pip和大多数Python库（如requests、urllib3）会自动拾取这些变量，无需额外配置。

Linux和macOS

# 无需身份验证
export HTTP_PROXY="http://1.2.3.4:8080"
export HTTPS_PROXY="http://1.2.3.4:8080"

# 带用户名和密码
export HTTP_PROXY="http://user:[email protected]:8080"
export HTTPS_PROXY="http://user:[email protected]:8080"

# SOCKS5代理
export HTTP_PROXY="socks5://user:[email protected]:1080"
export HTTPS_PROXY="socks5://user:[email protected]:1080"

# 现在安装包
pip install requests

为了避免每次都输入命令，可以将这些行添加到~/.bashrc或~/.zshrc中。

Windows（PowerShell）

# 临时（仅适用于当前会话）
$env:HTTP_PROXY = "http://user:[email protected]:8080"
$env:HTTPS_PROXY = "http://user:[email protected]:8080"

# 永久（适用于所有会话）
[System.Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://user:[email protected]:8080", "User")
[System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://user:[email protected]:8080", "User")

Windows（cmd）

set HTTP_PROXY=http://user:[email protected]:8080
set HTTPS_PROXY=http://user:[email protected]:8080
pip install numpy

请注意：如果密码中包含特殊字符（如@、#、%），需要进行URL编码。例如，@变为%40。

--proxy标志直接在pip中使用

如果只需为一个命令使用代理，而不更改全局设置： 

pip install pandas --proxy http://user:[email protected]:8080

# 对于SOCKS5需要安装pysocks包
pip install pysocks
pip install scikit-learn --proxy socks5://user:[email protected]:1080

通过pip.conf和pip.ini配置代理

如果您希望在每次运行pip时自动使用代理——无需手动导出变量——请将其写入pip的配置文件中。

配置文件的位置

操作系统 文件路径 作用域
Linux / macOS ~/.config/pip/pip.conf 当前用户
Linux / macOS /etc/pip.conf 系统所有用户
Windows %APPDATA%\pip\pip.ini 当前用户
任何操作系统 ./pip.conf（在项目文件夹中） 仅当前项目

pip.conf文件的内容

[global]
proxy = http://user:[email protected]:8080

# 如果需要忽略SSL验证（不推荐在生产环境中使用）
# trusted-host = pypi.org
#                files.pythonhosted.org

保存文件后，所有后续的pip install调用将自动使用指定的代理。可以通过以下命令检查当前配置： 

pip config list
pip config debug  # 显示所有配置文件及其优先级

选择哪种类型的代理用于PyPI

并非所有代理都适合与PyPI一起使用。选择取决于封锁的原因和您的基础设施。

代理类型 速度 可靠性 最佳场景
数据中心 ⚡ 高速 中等 企业网络、CI/CD、大包下载
住宅 中等 ⭐ 高 区域封锁，当数据中心IP也被封锁时
移动 中等 ⭐ 高 严格的区域封锁，需要最大程度的绕过
SOCKS5 ⚡ 高速 高 需要为所有流量（包括DNS）提供代理时

对于大多数面临因区域限制而封锁PyPI的开发者来说，最佳选择是数据中心代理——它们提供高下载速度和稳定的连接。速度尤其重要，当需要安装像PyTorch或TensorFlow这样的大型包（几个GB）时。

如果数据中心IP在您所在地区也被封锁（在严格的国家限制下会发生这种情况），可以考虑使用住宅代理——它们使用真实家庭用户的IP，受到封锁的可能性显著降低。

HTTP与HTTPS与SOCKS5：pip支持什么？

Pip原生支持HTTP和HTTPS代理。对于SOCKS5，需要安装额外的包： 

# 在pip中支持SOCKS5需要pysocks
# 但有一个问题：pip需要安装pysocks，而pip在没有代理的情况下无法工作
# 解决方案：先通过HTTP代理安装，然后切换到SOCKS5

pip install pysocks --proxy http://1.2.3.4:8080
# 之后可以使用SOCKS5
pip install requests --proxy socks5://user:[email protected]:1080

PyPI镜像作为代理的替代方案

如果配置代理看起来很复杂，或者您没有可靠的代理服务器，可以使用官方和非官方的PyPI镜像。这对于在中国的开发者尤其重要，因为那里有几个快速的本地镜像。

流行的PyPI镜像

镜像 URL 区域/运营商
清华大学 https://pypi.tuna.tsinghua.edu.cn/simple 中国（清华大学）
阿里云 https://mirrors.aliyun.com/pypi/simple 中国（阿里云）
USTC https://pypi.mirrors.ustc.edu.cn/simple 中国（USTC）
华为云 https://repo.huaweicloud.com/repository/pypi/simple 中国（华为）

如何使用镜像

# 一次性，通过-i标志
pip install numpy -i https://pypi.tuna.tsinghua.edu.cn/simple

# 永久，通过pip.conf
# [global]
# index-url = https://pypi.tuna.tsinghua.edu.cn/simple
# trusted-host = pypi.tuna.tsinghua.edu.cn

# 多个源（回退）
pip install pandas \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --extra-index-url https://pypi.org/simple/

⚠️ 关于镜像安全的重要提示

仅使用大型组织（大学、云服务提供商）提供的经过验证的镜像。未知的镜像可能包含带有恶意代码的修改包——这被称为供应链攻击（supply chain attack）。对于关键项目，最好通过devpi或bandersnatch搭建自己的镜像。

Docker和CI/CD中的pip代理

在构建Docker镜像时，pip在容器内运行，可能无法访问PyPI。这在企业CI/CD管道（如GitLab CI、GitHub Actions、Jenkins）中尤其常见。

通过ARG在Dockerfile中传递代理

FROM python:3.11-slim

# 声明代理的ARG
ARG HTTP_PROXY
ARG HTTPS_PROXY

# 传递到ENV供pip和其他工具使用
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 安装后重置代理（安全性）
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

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

通过传递代理进行构建： 

docker build \
  --build-arg HTTP_PROXY=http://user:[email protected]:8080 \
  --build-arg HTTPS_PROXY=http://user:[email protected]:8080 \
  -t myapp .

Docker守护进程的全局代理设置

# 文件：~/.docker/config.json
{
  "proxies": {
    "default": {
      "httpProxy": "http://user:[email protected]:8080",
      "httpsProxy": "http://user:[email protected]:8080",
      "noProxy": "localhost,127.0.0.1"
    }
  }
}

GitLab CI / GitHub Actions

# .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://user:[email protected]:8080"
  HTTPS_PROXY: "http://user:[email protected]:8080"
  PIP_INDEX_URL: "https://pypi.tuna.tsinghua.edu.cn/simple"

install:
  script:
    - pip install -r requirements.txt
# .github/workflows/ci.yml
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: ${{ secrets.HTTP_PROXY }}
      HTTPS_PROXY: ${{ secrets.HTTP_PROXY }}
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: pip install -r requirements.txt

重要提示：切勿在YAML文件中硬编码代理凭据。请使用您的CI/CD服务的秘密（Secrets）。

为Poetry、conda和uv配置代理

现代Python项目越来越多地使用替代包管理器。我们将讨论为每个包管理器配置代理的方法。

Poetry

Poetry使用环境变量与pip相同。但有一个细节——Poetry使用基于requests的自定义HTTP客户端，因此标准变量有效： 

# 对于Poetry有效
export HTTPS_PROXY=http://user:[email protected]:8080
poetry install

# 或在pyproject.toml中配置源
# [[tool.poetry.source]]
# name = "tsinghua"
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
# priority = "primary"

conda / mamba

conda有自己的配置系统： 

# 通过命令
conda config --set proxy_servers.http http://user:[email protected]:8080
conda config --set proxy_servers.https http://user:[email protected]:8080

# 或直接在~/.condarc中
# proxy_servers:
#   http: http://user:[email protected]:8080
#   https: http://user:[email protected]:8080

# 中国的conda镜像
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --set show_channel_urls yes

uv（新的快速包管理器）

uv来自Astral，是Python中最快的包管理器之一。它也支持标准环境变量： 

export HTTPS_PROXY=http://user:[email protected]:8080
uv pip install numpy

# 或使用index标志
uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

pipenv

# pipenv从pip继承环境变量
export HTTPS_PROXY=http://user:[email protected]:8080
pipenv install requests

# 在Pipfile中更改源
# [[source]]
# url = "https://pypi.tuna.tsinghua.edu.cn/simple"
# verify_ssl = true
# name = "tsinghua"

常见错误及其解决方法

我们将讨论开发者在为pip配置代理时遇到的最常见问题。

错误1：SSL证书验证失败

# 错误：
# SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate

# 原因：企业代理替换了SSL证书（MITM）
# 解决方案1：添加企业CA证书
pip install requests --cert /path/to/corporate-ca.crt

# 解决方案2：在pip.conf中指定证书路径
# [global]
# cert = /path/to/corporate-ca.crt

# 解决方案3（不推荐在生产环境中使用）：禁用SSL验证
pip install requests --trusted-host pypi.org --trusted-host files.pythonhosted.org

错误2：407代理身份验证所需

# 错误：
# ProxyError: 407 Proxy Authentication Required

# 原因：代理需要身份验证，但未提供用户名/密码
# 解决方案：确保凭据正确编码

# 如果密码包含特殊字符，请对其进行编码：
python3 -c "from urllib.parse import quote; print(quote('my@pass#word'))"
# 输出：my%40pass%23word

export HTTPS_PROXY="http://user:my%40pass%[email protected]:8080"

错误3：pip忽略环境变量

# 检查变量是否正确设置
echo $HTTPS_PROXY  # Linux/macOS
echo %HTTPS_PROXY%  # Windows cmd

# 检查pip的配置优先级
pip config debug

# 可能的原因：虚拟环境无法看到系统变量
# 解决方案：激活venv并重新设置变量
source venv/bin/activate
export HTTPS_PROXY=http://1.2.3.4:8080
pip install package-name

错误4：即使通过代理也超时连接

# 检查代理的可用性
curl -v --proxy http://user:[email protected]:8080 https://pypi.org/simple/

# 如果代理不可用——问题出在代理服务器本身
# 尝试其他端口或协议

# 增加pip的超时
pip install package-name --timeout 120

# 或在pip.conf中：
# [global]
# timeout = 120

错误5：包已安装，但导入不工作

这与代理无关——很可能包安装在系统Python中，而不是在活动的虚拟环境中。请检查： 

which pip      # 应指向venv中的pip
which python   # 应指向venv中的python
pip show requests  # 将显示包安装的位置

pip代理调试清单

逐步诊断：

  1. 检查没有代理的情况下PyPI的可用性：curl https://pypi.org
  2. 确保代理服务器正常工作：curl --proxy http://1.2.3.4:8080 https://pypi.org
  3. 检查环境变量：env | grep -i proxy
  4. 查看pip配置：pip config debug
  5. 尝试直接使用标志：pip install pkg --proxy http://... -v
  6. 如果出现SSL错误——检查企业CA证书
  7. 如果仍然无法工作——尝试使用镜像代替代理

结论

封锁PyPI是一个可解决的问题，并且有几种可靠的解决方案。要快速入门，只需设置HTTPS_PROXY变量，然后像往常一样运行pip。要实现持续工作——在pip.conf中配置代理。对于CI/CD——使用秘密和Docker中的ARG。

在代理和镜像之间的选择取决于上下文：镜像更快且更易于配置，但需要信任镜像的运营商。代理更通用——它不仅适用于PyPI，还适用于任何其他被封锁的资源（npm、Docker Hub、GitHub）。

如果您需要一个可靠的代理来处理PyPI、GitHub、Docker Hub和您所在地区的其他被封锁资源，请考虑数据中心代理——它们在下载大型包时提供高速度，并在CI/CD环境中稳定工作。如果您所在地区甚至封锁了数据中心的IP，请考虑使用住宅代理，这些代理使用真实家庭用户的IP，受到区域封锁的可能性显著降低。

```