Как настроить pip для приватного PyPI: логин, токен, netrc и keyring

Какие способы аутентификации понимает pip

Для приватного индекса pip может получить имя пользователя и пароль из URL вида `https://user:password@example.com/simple`, из файла `.netrc` или через keyring. В некоторых registry вместо обычного пароля используется API-токен; документация pip отдельно отмечает, что токен может применяться как имя пользователя без пароля, если так устроена конкретная служба. Встраивание секрета в URL технически работает, но создаёт больше мест утечки: shell history, логи CI, диагностический вывод, скриншоты и файлы конфигурации. `.netrc` убирает пароль из команды, однако это всё равно файл с секретом, к правам доступа которого нужно относиться внимательно. Keyring позволяет передать хранение учётных данных системному или поддерживаемому backend и обычно удобнее на рабочей машине. В корпоративной среде окончательный способ должен совпадать с политикой вашего registry: например, одноразовый токен, персональный access token или short-lived credential.

Важно: Если секрет уже попал в URL, лог CI или историю shell, считайте его раскрытым: отзовите токен и выпустите новый. Простого удаления строки из конфигурации недостаточно.

Настройка через keyring без пароля в команде

1. Установите backend keyring: Убедитесь, что пакет `keyring` и нужный backend доступны тому же интерпретатору Python, которым запускается pip.
2. Проверьте адрес индекса: Сначала задайте или проверьте `index-url` без встраивания секрета, например через конфигурацию pip или переменную окружения, принятую в вашей среде.
3. Сохраните учётные данные поддерживаемым способом: Используйте keyring/backend или механизм вашего registry для сохранения логина и токена. Не коммитьте секрет в `pip.conf`, `pip.ini` или `pyproject.toml`.
4. Выполните тестовый запрос: Запустите установку заведомо существующего приватного пакета с подробностью, достаточной для диагностики, но не публикуйте необработанный лог в открытом issue.
5. Проверьте неинтерактивный сценарий: Отдельно протестируйте CI: режим keyring `auto` ведёт себя иначе, когда pip запущен с `--no-input`, поэтому интерактивно работающая схема может потребовать явной настройки провайдера.

Предупреждение: Документация pip предупреждает: при `--no-input` провайдер keyring `auto` не запрашивает keyring, чтобы не зависнуть на интерактивном вводе. Это важно для CI.

Basic Auth, .netrc и keyring: когда что выбирать

[object Object]

Почему пароль со спецсимволами даёт 401 даже при правильных данных

Если вы всё же используете credentials в URL, зарезервированные символы должны быть percent-encoded. Например, символы вроде `/`, `@`, `:` или `#` имеют специальное значение в URL и без кодирования могут изменить разбор адреса до того, как запрос дойдёт до registry. В таком случае сервер отвечает 401 или запрос вообще уходит не туда, хотя пользователь уверен, что пароль введён верно. pip прямо ссылается на percent-encoding для специальных символов в credentials. Не пытайтесь лечить такую ошибку отключением TLS-проверки или добавлением `--trusted-host`: проблема аутентификации и проблема доверия сертификату — разные классы неисправностей. Сначала проверьте конечный host, `index-url`, логин и способ передачи токена, затем уже разбирайте сетевую часть. Для воспроизводимой настройки полезно проверить `python -m pip config debug`: он показывает, какие конфигурационные файлы и значения реально подхвачены.

Совет: Секрет с `@` или `:` в URL без кодирования может выглядеть правдоподобно, но парситься иначе. Лучше вовсе не помещать постоянный секрет в URL.

Как разбирать 401, 403 и случайный доступ к публичному PyPI

401 обычно указывает, что registry не принял аутентификацию: проверьте истёкший токен, имя пользователя, область действия токена и тот ли credential source использует pip. 403 чаще означает, что сервер понял, кто вы, но запрещает конкретное действие или ресурс; точная семантика зависит от registry, поэтому смотрите его документацию и серверный ответ. Ещё одна частая ловушка — неверный `index-url` или сочетание `index-url` и `extra-index-url`, из-за которого пакет находится не в том источнике, который ожидал пользователь. Не делайте вывод по одному имени пакета: сравните фактический URL запроса и источник скачанного артефакта. При отладке не публикуйте полный verbose-лог без просмотра: маскирование pip снижает риск, но нельзя рассчитывать, что сторонние скрипты, прокси или wrapper тоже скроют секреты. Для автоматизации создавайте токен с минимально необходимыми правами и отдельной ротацией, а не используйте личный пароль разработчика.

Важно: Для CI лучше отдельный read-only credential, если задача только устанавливает пакеты. Это уменьшает ущерб при компрометации runner или лога.

Чек-лист безопасной конфигурации приватного индекса

• Точный URL `/simple` или другой endpoint подтверждён документацией вашего registry.
• Проверено, какой формат логина/токена ожидает именно этот registry.
• Постоянный секрет не записан в репозиторий, Dockerfile или публичный CI-лог.
• Если используется URL с credentials, спецсимволы percent-encoded.
• Для `.netrc` ограничен доступ к файлу и проверено имя машины.
• Для keyring установлен backend и отдельно протестирован режим CI/`--no-input`.
• При ошибке 401/403 проверяются права токена и фактический источник пакета, а не отключается TLS.
• Токен можно быстро отозвать и заменить без изменения исходного кода проекта.

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

Если вы всё же используете credentials в URL, зарезервированные символы должны быть percent-encoded. Например, символы вроде `/`, `@`, `:` или `#` имеют специальное значение в URL и без кодирования могут изменить разбор адреса до того, как запрос дойдёт до registry. В таком случае сервер отвечает 401 или запрос вообще уходит не туда, хотя пользователь уверен, что пароль введён верно. pip прямо ссылается на percent-encoding для специальных символов в credentials. Не пытайтесь лечить такую ошибку…

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

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

• Authentication — pip documentation