Настройка pip через прокси: пошаговое руководство

Кратко: почему pip лучше запускать через промежуточный сервер (proxy)?

Во многих корпоративных и изолированных сетях установлены жёсткие ограничения на прямое подключение к интернету. Это создаёт сложности при загрузке библиотек для Python из внешних источников. Решить задачу помогает настройка соединения через промежуточный сервер (proxy), который обеспечивает безопасную передачу данных через разрешённые каналы. Такой подход не только соответствует политике информационной безопасности компании, но и позволяет получать последние версии пакетов из официальных и локальных репозиториев. Настройка proxy может выполняться по-разному: через параметры запуска, конфигурационные файлы или переменные среды. Подробности — в этом руководстве.

Способ 1. Указываем адрес прокси прямо в командной строке

Проще всего «проверить на лету», что загрузка пакета пойдёт через нужный узел, — добавить параметр –proxy к установленной команде.

pip install <имя_пакета> --proxy http://<логин>:<пароль>@<proxy-host>:<порт>

Подставьте собственные значения вместо <логин>, <пароль>, <proxy-host> и <порт>. Если авторизация не нужна, достаточно:

pip install <имя_пакета> --proxy http://<proxy-host>:<порт>

Формат вызова одинаков для Linux, macOS и Windows, поэтому при разовой установке это самый быстрый вариант. Минус — параметр придётся добавлять вручную каждый раз, поэтому для постоянной работы лучше воспользоваться конфиг-файлом или переменными окружения.

Способ 2. Указываем промежуточный сервер (proxy) в конфигурационном файле pip

Чтобы задать адрес сервера один раз и каждый раз пользоваться им автоматически, удобно внести параметр proxy в конфигурационный файл. Утилита читает настройки с трёх уровней: системного, пользовательского и локального (расположенного прямо внутри виртуального окружения). Ниже перечислены все стандартные пути и рекомендации по созданию файлов, если их нет.

Где находится / как создать файл настроек pip

Pip ищет файлы конфигурации в стандартных местах в зависимости от вашей ОС:

•  Linux/macOS: файл конфигурации пользователя обычно находится в ~/. config/pip/pip.conf на современных системах. (Он также будет читать устаревшую конфигурацию в ~/.pip/pip.conf, если она существует.) На macOS вы также можете использовать ~/Library/Application Support/pip/pip.conf, если эта директория существует. Если файл ещё не существует, вам нужно будет создать его вместе с каталогами.
• Windows: В Windows файл конфигурации называется pip.ini и хранится в вашем каталоге %APPDATA%\pip\. Например, для пользователя по имени Jhon в Windows 10, путь файла будет C:\Users\Jhon\AppData\Roaming\pip\pip.ini. Вам может понадобиться создать папку pip Python под AppData\Roaming, если ее там нет, а затем создать файл с именем pip.ini внутри нее.

Примечание: есть также общесистемные (“глобальные”) файлы конфигурации (например, /etc/pip.conf на Linux или C: ProgramData pip pip.ini на Windows), а также файлы конфигурации “сайта” для конкретных виртуальных сред. В большинстве случаев использование конфигурации для каждого пользователя является достаточным и не требует прав администратора.

Пример для Linux и macOS

Откройте (или создайте) файл ~/.config/pip/pip.conf в домашней директории. Если его нет, создайте обычный текстовый файл с таким именем.

Добавьте в него строки:

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

Теперь любой вызов pip автоматически использует промежуточный сервер из pip.conf

Пример для Windows

На Windows, откройте файл %APPDATA% pip.ini (создайте его, если требуется). Добавьте то же самое в формате INI:

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

Снова подставьте реальные параметры вашего сервера.

Например, если промежуточный сервер доступен по адресу proxywing:3128 и не требует авторизации, строка будет такой: proxy = http://proxywing:3128

Не забудьте оставить заголовок [global], как показано выше.

После сохранения файла pip.ini pip автоматически будет использовать указанный сервер для всех операций

Какие параметры записать в файл конфигурации

Единственное, что вам нужно включить, — это саму настройку сервера в разделе [global].

Имя ключа — буквально proxy, оно соответствует опции –proxy.

Добавлять переменные http_proxy или https_proxy не требуется — конфигурация использует единый параметр proxy для любых схем URL.

Если у вас есть отдельные HTTP- и HTTPS, обычно достаточно указать только HTTPS: он будет применяться и к HTTP-, и к HTTPS-запросам без дополнительных флагов. После добавления строки с сервером и сохранения файла настройка завершена.

Для проверки запустите команду pip (например, pip download <package>) и убедитесь, что она выполняется без ошибок, связанных с промежуточным сервером. pip автоматически применит сервер из конфигурации. Если когда-нибудь нужно временно отключить промежуточный сервер, удалите или закомментируйте строку proxy = … или запустите команду с флагом –proxy “”, чтобы переопределить настройку для конкретного запуска.

Способ 3. Настройка прокси через переменные окружения

Ещё один способ указать промежуточный сервер по умолчанию — задать соответствующие переменные окружения системы. При наличии переменных HTTP_PROXY и HTTPS_PROXY (а также опционально NO_PROXY для исключений) инструмент установки пакетов будет автоматически направлять свои запросы через указанный сервер.

Синтаксис для Linux / macOS

В Unix-подобных системах переменные можно временно установить в текущей сессии оболочки или прописать в профиль пользователя для постоянного действия. Формат команд:

export HTTP_PROXY="http://<адрес_proxy>:<порт>"
export HTTPS_PROXY="http://<адрес_proxy>:<порт>"

Если промежуточный сервер требует авторизацию, включите логин и пароль в URL (аналогично примерам выше). Для постоянной настройки добавьте эти строки в файл конфигурации вашей оболочки (например, ~/.bashrc или ~/.zshrc). После этого при каждом запуске терминала переменные будут устанавливать себя автоматически.

Синтаксис для Windows

В Windows переменные окружения можно установить с помощью утилиты setx. Запустите командную строку (CMD) или PowerShell от имени администратора и выполните:

setx HTTP_PROXY "http://<адрес_proxy>:<порт>" /M
setx HTTPS_PROXY "http://<адрес_proxy>:<порт>" /M

Ключ /M задаёт переменную на уровне всей системы (для всех пользователей). После успешного выполнения команд закройте и заново откройте консоль, чтобы новые переменные вступили в силу. Теперь утилита будет автоматически использовать указанный proxy-сервер для всех сетевых операций pip.

(Примечание: если опустить параметр /M, переменные пропишутся только для текущего пользователя.)

Проверяем, что промежуточный сервер (proxy) работает для pip

После настройки промежуточного сервера важно убедиться, что всё функционирует корректно. Самый простой способ – попробовать установить какой-нибудь пакет и проверить, проходит ли соединение.

Linux / macOS

Откройте терминал и выполните команду, например:

$ pip install requests
Collecting requests

 Downloading requests-2.30.0-py3-none-any.whl (62 kB)

 ---------------------------------------- 62.0/62.0 kB 2.0 MB/s eta 0:00:00

Collecting charset-normalizer<4,>=2

 Downloading charset_normalizer-3.1.0-py3-none-any.whl (50 kB)

 ---------------------------------------- 50.0/50.0 kB 1.3 MB/s eta 0:00:00

Collecting idna<4,>=2.5

 Downloading idna-3.4-py3-none-any.whl (61 kB)

 ---------------------------------------- 61.5/61.5 kB 1.5 MB/s eta 0:00:00

Collecting urllib3<3,>=1.21.1

 Downloading urllib3-2.0.3-py3-none-any.whl (123 kB)

 ---------------------------------------- 123.6/123.6 kB 2.5 MB/s eta 0:00:00

Collecting certifi>=2017.4.17

 Downloading certifi-2023.5.7-py3-none-any.whl (156 kB)

 ---------------------------------------- 156.7/156.7 kB 3.1 MB/s eta 0:00:00

Installing collected packages: certifi, urllib3, idna, charset-normalizer, requests

Successfully installed certifi-2023.5.7 charset-normalizer-3.1.0 idna-3.4 requests-2.30.0 urllib3-2.0.3

Windows

В Windows откройте командную строку и выполните ту же команду:

C:\> pip install requests
Collecting requests

 Downloading requests-2.30.0-py3-none-any.whl (62 kB)

 ---------------------------------------- 62.0/62.0 kB <speed> <time>

Collecting certifi>=2017.4.17

 Downloading certifi-2023.5.7-py3-none-any.whl (156 kB)

 ---------------------------------------- 156.7/156.7 kB <speed> <time>

... (additional output omitted for brevity) ...

Successfully installed certifi-2023.5.7 charset-normalizer-3.1.0 idna-3.4 requests-2.30.0 urllib3-2.0.3

pip прокси в виртуальных окружениях

Виртуальная среда, созданная через venv, virtualenv или conda, по умолчанию принимает сетевые параметры от основной системы — в том числе адрес промежуточного сервера (proxy). Если же для проекта нужен другой адрес либо его нельзя тянуть извне, настройку легко «зашить» прямо внутрь окружения. Самый очевидный путь — кинуть собственный конфиг рядом с окружением: для Linux и macOS это файл pip.conf, а для Windows — pip.ini, расположенный внутри каталога среды возле папок bin/ или Scripts/. Утилита сначала ищет настройки именно там, и локальный файл перекроет глобальные правила. Второй вариант — прописать переменные HTTP_PROXY и HTTPS_PROXY в скрипт активации (тот самый bin/activate или Scripts\\Activate.ps1). После этого при каждом «входе» в окружение нужные значения подхватываются автоматически, а за его пределами остаётся чистая конфигурация системы.

Частые проблемы и их решения при работе с прокси

Настройка proxy для pip обычно проста, но иногда возникают нюансы:

• Ошибка 407 Proxy Authentication Required. Возникает, если промежуточный сервер требует имя пользователя и пароль, а утилита передаёт неверные креденшалы. Решение: убедитесь, что URL промежуточного сервера прописан правильно, включая логин/пароль, и что учётные данные действительны. Если пароль содержит специальные символы, возможно, их требуется URL-кодировать (например, @ заменить на %40).
• Ошибки SSL-сертификата. При использовании HTTPS может появиться ошибка вида SSL: Certificate verify failed. Это происходит, если промежуточный сервер использует самоподписанный сертификат для перехвата трафика, которому pip не доверяет. Простейший обходной путь – запустить установку с опцией –trusted-host для доменов PyPI. 

Например:

pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org <package>

Эта команда позволит менеджеру пакетов игнорировать недоверенный сертификат для указанных хостов. Более правильный подход – добавить сертификат промежуточного сервера в доверенные на уровне системы или указать pip использовать файл сертификатов (через опцию –cert или переменную REQUESTS_CA_BUNDLE), но это выходит за рамки данного руководства.

• Блокировки и лимиты по IP. Если вы выполняете массовые установки или скрипты, многократно обращающиеся к PyPI, ваш исходящий IP может быть временно заблокирован за подозрительную активность. В таких случаях поможет использование ротирующихся серверов (proxy– сервиса), который автоматически меняет IP-адрес для каждого запроса. С точки зрения pip достаточно указать адрес такого сервера (или нескольких поочерёдно) в параметрах или конфиге – смена IP происходит на стороне промежуточно сервера-провайдера.
• Переменные окружения не учитываются. Если вы задали переменные, но pip всё равно не пытается подключаться через промежуточный сервер, убедитесь, что переменные установлены в той же сессии, где запускается команда. На Linux имена переменных чувствительны к регистру: используйте заглавные HTTP_PROXY/HTTPS_PROXY (некоторые дистрибутивы также распознают нижний регистр). На Windows после команды setx необходимо открыть новое окно терминала. Также проверьте, не переопределена ли конфигурация промежуточного сервера через переменную PIP_CONFIG_FILE (её значение должно быть пустым или неопределено).

Заключение

Настройка инструмента установки Python-пакетов для работы через промежуточный сервер важна всякий раз, когда вы управляете зависимостями в защищённых или ограниченных сетях. В статье разобраны три основных подхода:

• Флаг –proxy — быстрый способ для разовых установок и проверки доступа.
• Файл конфигурации — удобно, если нужно постоянное правило на конкретной машине.
• Переменные окружения — оптимальны, когда хотим, чтобы через тот же промежуточный сервер обращались и другие программы, а не только утилита установки.

Мы также посмотрели, как эти приёмы работают внутри виртуальных окружений, и обсудили типичные сбои: отказ в аутентификации, ошибки проверки SSL-сертификатов и ответы вида 403 Forbidden.

Выберите метод, который лучше вписывается в ваш сценарий. Файл конфигурации идеален для устойчивой настройки одного устройства, а переменные окружения удобны, если сервер должен обслуживать весь инструментарий целиком. Не забудьте убрать или скорректировать параметры, когда покинете корпоративную сеть — иначе трафик будет уходить на несуществующий сервер.

Попробуйте прямо сейчас: протестируйте любой из описанных способов и убедитесь, что установка библиотек проходит через ваш сервер. При корректной конфигурации работа за файрволом становится такой же беспроблемной, как и в открытом интернете. Успехов в разработке — сохраните это руководство, чтобы при необходимости быстро повторить настройк.