Прокси для PyPI: установка Python-пакетов в обход блокировок

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.

Временные сбои и rate-limiting

Иногда PyPI сам ограничивает количество запросов с одного IP — особенно если вы разворачиваете десятки Docker-контейнеров одновременно. В этом случае прокси с ротацией IP решает проблему.

Как проверить, заблокирован ли PyPI?

Выполните в терминале: curl -v https://pypi.org/simple/. Если соединение зависает или выдаёт ошибку SSL/timeout — PyPI недоступен с вашего IP. Если ошибка содержит слово 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. Выбор зависит от причины блокировки и вашей инфраструктуры.

Тип прокси	Скорость	Надёжность	Лучший сценарий
Datacenter	⚡ Высокая	Средняя	Корпоративные сети, CI/CD, скачивание больших пакетов
Residential	Средняя	⭐ Высокая	Региональные блокировки, когда datacenter IP тоже заблокированы
Mobile	Средняя	⭐ Высокая	Жёсткие региональные блокировки, когда нужен максимальный обход
SOCKS5	⚡ Высокая	Высокая	Когда нужен прокси для всего трафика, включая DNS

Для большинства разработчиков, которые сталкиваются с блокировкой PyPI из-за региональных ограничений, оптимальным выбором будут прокси дата-центров — они обеспечивают высокую скорость скачивания пакетов и стабильное соединение. Скорость особенно важна, когда нужно установить тяжёлые пакеты вроде PyTorch или TensorFlow (несколько гигабайт).

Если же datacenter IP тоже блокируются в вашем регионе (такое бывает при жёстких государственных ограничениях), стоит рассмотреть резидентные прокси — они используют IP реальных домашних пользователей и значительно реже попадают под блокировки.

HTTP vs HTTPS vs SOCKS5: что поддерживает pip?

Pip поддерживает HTTP и HTTPS прокси нативно. Для SOCKS5 нужно установить дополнительный пакет:

# Для поддержки SOCKS5 в pip нужен 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. Это особенно актуально для разработчиков в Китае, где есть несколько быстрых локальных зеркал.

Зеркало	URL	Регион / Оператор
Tsinghua	`https://pypi.tuna.tsinghua.edu.cn/simple`	Китай (Университет Цинхуа)
Aliyun	`https://mirrors.aliyun.com/pypi/simple`	Китай (Alibaba Cloud)
USTC	`https://pypi.mirrors.ustc.edu.cn/simple`	Китай (USTC)
Huawei Cloud	`https://repo.huaweicloud.com/repository/pypi/simple`	Китай (Huawei)

Как использовать зеркало

# Разово, через флаг -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

# Несколько источников (fallback)
pip install pandas \
  -i https://pypi.tuna.tsinghua.edu.cn/simple \
  --extra-index-url https://pypi.org/simple/

⚠️ Важно про безопасность зеркал

Используйте только проверенные зеркала от крупных организаций (университеты, облачные провайдеры). Неизвестные зеркала могут содержать модифицированные пакеты с вредоносным кодом — это называется атакой на цепочку поставок (supply chain attack). Для критических проектов лучше поднять собственное зеркало через devpi или bandersnatch.

Прокси для pip в Docker и CI/CD

При сборке 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 daemon

# Файл: ~/.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-файлах. Используйте секреты (Secrets) вашего CI/CD-сервиса.

Настройка прокси для Poetry, conda и uv

Современные Python-проекты всё чаще используют альтернативные менеджеры пакетов. Рассмотрим настройку прокси для каждого из них.

Poetry

Poetry использует переменные окружения так же, как и pip. Но есть нюанс — Poetry использует собственный HTTP-клиент на базе requests, поэтому стандартные переменные работают:

# Работает для 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 Certificate Verification Failed

# Ошибка:
# 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 Proxy Authentication Required

# Ошибка:
# 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: Connection timeout даже через прокси

# Проверьте доступность прокси
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      # должен указывать на pip внутри venv
which python   # должен указывать на python внутри venv
pip show requests  # покажет, куда установлен пакет

Чек-лист отладки прокси для pip

Пошаговая диагностика:

Проверьте доступность PyPI без прокси: curl https://pypi.org
Убедитесь, что прокси-сервер работает: curl --proxy http://1.2.3.4:8080 https://pypi.org
Проверьте переменные окружения: env | grep -i proxy
Посмотрите конфигурацию pip: pip config debug
Попробуйте флаг напрямую: pip install pkg --proxy http://... -v
Если SSL ошибки — проверьте корпоративный CA-сертификат
Если всё равно не работает — попробуйте зеркало вместо прокси

Заключение

Блокировка PyPI — решаемая проблема, и у неё есть несколько надёжных решений. Для быстрого старта достаточно выставить переменную HTTPS_PROXY и запустить pip как обычно. Для постоянной работы — прописать прокси в pip.conf. Для CI/CD — использовать секреты и ARG в Docker.

Выбор между прокси и зеркалом зависит от контекста: зеркала быстрее и проще в настройке, но требуют доверия к оператору зеркала. Прокси универсальнее — он работает не только с PyPI, но и с любыми другими заблокированными ресурсами (npm, Docker Hub, GitHub).

Если вам нужен надёжный прокси для работы с PyPI, GitHub, Docker Hub и другими заблокированными ресурсами в вашем регионе, обратите внимание на прокси дата-центров — они обеспечивают высокую скорость при скачивании тяжёлых пакетов и стабильно работают в CI/CD окружениях. Если же в вашем регионе блокируются даже IP дата-центров, рассмотрите резидентные прокси с IP реальных домашних пользователей — они значительно реже попадают под региональные блокировки.

Прокси для PyPI: как установить Python-пакеты в заблокированных регионах через pip