pip --isolated: как игнорировать конфиг и переменные окружения

Что именно делает pip --isolated

pip получает настройки сразу из нескольких слоёв: командной строки, переменных окружения и конфигурационных файлов. Поэтому одна и та же команда установки может вести себя по-разному на ноутбуке разработчика и в CI, хотя requirements одинаковы. Опция `--isolated` нужна для controlled test: официальная CLI-документация pip указывает, что в этом режиме игнорируются environment variables и user configuration. Это не «полный стерильный контейнер» и не сброс всех системных условий Python; она лишь убирает определённые источники конфигурации pip. Именно поэтому режим особенно полезен, когда вы подозреваете `PIP_INDEX_URL`, `PIP_PROXY`, пользовательский `pip.conf` или другую настройку, которая незаметно влияет на установку.

Совет: Для диагностики вызывайте pip как `python -m pip`, чтобы явно использовать pip того Python-интерпретатора, который вы проверяете.

Как сравнить обычный и isolated-запуск

1. Зафиксируйте исходную ошибку обычной командой, например `python -m pip install <package>`. Сохраните полный текст ошибки, а не только последнюю строку.
2. Посмотрите активную конфигурацию через `python -m pip config debug`. Команда помогает увидеть, какие config files существуют и какие значения pip видит.
3. Проверьте переменные окружения с префиксом `PIP_` безопасным для вашей ОС способом. Не публикуйте токены приватного registry в логах или тикете.
4. Повторите тот же install с `python -m pip --isolated install <package>`. Не добавляйте одновременно новые index-url и proxy: иначе сравнение перестанет быть чистым.
5. Если isolated-вариант заработал, вернитесь к слоям конфигурации и найдите конкретное значение, которое меняет поведение. Удаляйте причину, а не используйте `--isolated` как вечный обход.
6. Если ошибка сохранилась, проблема вероятнее связана с сетью, сертификатами, доступностью пакета, Python/ABI, resolver или самим index, а не с пользовательскими env/config.

Предупреждение: Не вставляйте вывод окружения целиком в публичный issue: `PIP_INDEX_URL` и похожие переменные могут содержать credentials.

Какие уровни конфигурации есть у pip и почему это важно

Документация pip описывает конфигурационные файлы нескольких уровней, включая global, user и site, а также отдельный `PIP_CONFIG_FILE`. Поверх файлов действуют переменные окружения, а параметры командной строки имеют ещё более прямое влияние на конкретный запуск. Из-за такой иерархии разработчик может редактировать один `pip.conf`, но фактически значение приходит из другого источника. `pip config debug` полезен тем, что делает эти источники видимыми. Если задача — не просто диагностировать, а отключить загрузку config files в обычном режиме, документация также описывает `PIP_CONFIG_FILE` со значением `os.devnull`; это отдельный механизм и его не нужно путать с `--isolated`.

Обычный pip, --isolated и отключение config files

• Обычный `python -m pip`. Стандартные config files, env и CLI по правилам precedence. Повседневная работа
• `python -m pip --isolated`. Игнорирует pip env variables и user configuration. A/B-диагностика локальных настроек
• `PIP_CONFIG_FILE=os.devnull`. Отключает загрузку config files по описанному pip механизму. Точечная проверка влияния файлов конфигурации
• Свежий venv/container. Изолирует гораздо больше состояния окружения. Проверка воспроизводимости среды в целом

Важно: `--isolated` не означает, что сеть, сертификаты, DNS, Python version и системные библиотеки становятся одинаковыми с CI.

Сценарий: pip ходит не в тот индекс

Один из самых понятных кейсов — команда ищет пакет в корпоративном mirror или приватном registry, хотя разработчик ожидает публичный индекс. Сначала `pip config debug` показывает, нет ли `index-url` в config file. Затем нужно проверить environment variable `PIP_INDEX_URL`. Если обычная команда использует неожиданный индекс, а isolated-команда меняет поведение, круг поиска резко сужается. После этого корректнее исправить конфигурацию в том месте, где она действительно задана: удалить устаревший user setting, изменить CI secret/variable или явно задать policy проекта. Постоянно добавлять `--isolated` в каждую команду только скрывает конфликт настроек.

Сценарий: proxy, trusted-host и сертификаты

Другой распространённый случай — локальный proxy или `trusted-host`, оставшийся после работы в закрытой сети. Isolated-режим может показать, что ошибка зависит от пользовательской конфигурации, но сам по себе не делает небезопасную схему безопасной. Не превращайте диагностику в отключение TLS-проверок и не копируйте случайные `trusted-host` команды из форумов. Если организации нужен proxy или собственный CA, настройка должна быть документирована и воспроизводима в нужном окружении. Для внешнего PyPI проблема сертификата требует понять цепочку доверия, системное время и interception proxy, а не просто «заставить pip игнорировать предупреждение».

Что записать после диагностики

• Версию Python и вывод `python -m pip --version`.
• Работает ли обычная команда и работает ли точно такая же команда с `--isolated`.
• Какие config-файлы видит `pip config debug` без публикации секретных значений.
• Есть ли `PIP_*` переменные, способные менять index, proxy или timeout.
• Какой URL/index фактически используется в подробном логе, если его безопасно показать.
• Воспроизводится ли проблема в свежем virtual environment.
• Не зависит ли результат от конкретной сети, VPN или корпоративного proxy.

Когда --isolated стоит использовать в CI

В CI isolated mode имеет смысл только как осознанная политика. Если pipeline должен полностью игнорировать пользовательские настройки runner-а, гораздо важнее контролировать сам runner, virtual environment, secrets и команды установки. На shared/self-hosted runner `--isolated` может защитить от части случайного user config, но не от системных файлов, сетевой инфраструктуры или установленного Python. В воспроизводимом pipeline лучше явно задавать нужный index, credential mechanism и certificate policy, а затем проверять, что job не зависит от состояния домашнего каталога. `--isolated` остаётся полезным дополнительным барьером и диагностическим инструментом, но не заменяет hermetic build design.

Что --isolated не игнорирует

Название isolated легко трактовать шире, чем это делает pip. Официальная CLI-справка формулирует поведение узко: режим игнорирует environment variables и user configuration; это не обещание отключить global/site config, сетевую политику ОС, прокси вне pip, сертификаты или настройки самого Python. Поэтому при расследовании сравнивайте не только две команды, но и вывод `pip config debug`: он показывает global, user и site уровни, а также помогает увидеть, какой файл существует в текущем virtual environment. Если нужно проверить влияние вообще всех конфигурационных файлов, это отдельный эксперимент с `PIP_CONFIG_FILE` и `os.devnull`, а не синоним `--isolated`. Такой разбор предотвращает ложный вывод «isolated не помог — значит конфигурации точно ни при чём».

Что учитывать

Документация pip описывает конфигурационные файлы нескольких уровней, включая global, user и site, а также отдельный `PIP_CONFIG_FILE`. Поверх файлов действуют переменные окружения, а параметры командной строки имеют ещё более прямое влияние на конкретный запуск. Из-за такой иерархии разработчик может редактировать один `pip.conf`, но фактически значение приходит из другого источника. `pip config debug` полезен тем, что делает эти источники видимыми. Если задача — не просто диагностировать, а…

Источники и проверка

Фактическая часть сверена по первичным источникам (в т.ч. pip command line interface). Пример и формулировки — редакция N1RO на 2026-09-21.

• pip command line interface
• pip configuration