#Что происходит и когда возникает ошибка
Локальный файл .whl можно установить без сети, но для успешной автономной установки должны совпасть теги платформы, версия Python и все зависимости. Наличие одного файла wheel ещё не гарантирует, что остальные пакеты доступны.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Не хватает зависимых wheelpip не может получить требуемые зависимости из пустого локального каталога. | Ошибка показывает No matching distribution found for ... при --no-index | Сформировать полный набор на совместимой сетевой машине. |
| Файл не подходит платформеИмя wheel содержит несовместимый тег ABI/архитектуры/версии. | Вывод not a supported wheel on this platform | Подобрать корректную сборку. |
| Используется не тот каталогПуть в --find-links относится к другой рабочей папке. | pip не видит лежащий рядом файл | Указать явный путь и проверить файлы. |
#Подробная диагностика и исправление
- Сначала уточните имя файла и целевой PythonВ папке с wheel проверьте имя
package-version-python_tag-abi_tag-platform_tag.whl. В терминале целевого компьютера запуститеpython -Vиpython -m pip debug --verbose; сравните поддерживаемые теги с файлом. Не переименовывайте wheel ради совпадения: это не изменит двоичную совместимость.Linux · Терминал (Bash)КомандаДиагностика локального Python; формат подробного вывода может меняться.python -Vpython -m pip debug --verbose
- Подготовьте отдельное окружение для автономного испытанияНа целевой машине создайте
.venv-offline, чтобы не затронуть работающие библиотеки. Проверьте, что там есть pip черезpython -m pip --version. Если создание venv требует ensurepip или системного пакета, подготовьте его заранее через разрешённый системный способ.
- Проверьте локальный каталог и полный набор пакетовСоздайте папку
wheelhouseи положите в неё основной wheel и колёса зависимостей. При доступе к сети на машине той же платформы заранее соберите наборpython -m pip download -d wheelhouse -r requirements.txt. Кроссплатформенная подготовка требует явных параметров тегов; простой набор для Linux обычно не подходит Windows.Linux · Терминал (Bash)КомандаВыполняется на проверенной машине с сетью и такой же платформой; сохраняет пакеты, не устанавливает их.python -m pip download -d wheelhouse -r requirements.txt
- Выполните офлайн-установку без обращения к индексуНа целевой машине из корня проекта активируйте .venv-offline либо запустите её Python напрямую. Команда
--no-index --find-links=wheelhouseищет файлы только в вашей папке; при отсутствии подходящего файла должна завершиться ошибкой, а не обращаться в сеть.Linux · Терминал (Bash)С осторожностьюПосле активации .venv-offline; папка wheelhouse и requirements.txt должны существовать. Затрагивает только тестовую среду.python -m pip install --no-index --find-links=wheelhouse -r requirements.txtКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- Если требуется только один wheelДля конкретного файла можно указать путь к нему:
python -m pip install --no-index --find-links=wheelhouse wheelhouse/ИМЯ.whl. Зависимости всё равно должны находиться в wheelhouse. Опция--no-depsподходит только когда все зависимости точно установлены и проверены; она не решает отсутствие зависимостей.
- Проверьте отсутствие неявной сети и целостностьСверьте контрольные суммы wheel с доверенным источником, особенно при переносе через носитель. Убедитесь, что в журнале нет обращения к внешнему индексу, затем выполните
python -m pip checkи тест приложения. При неуспехе восполните недостающую зависимость в wheelhouse на сетевой машине.
#Проверка результата и действия при неуспехе
Пакеты установлены из локальной папки без обращения к интернету, проверка зависимостей пройдена и приложение запускается.
Если исправление не помогло, вернитесь к точному сообщению об ошибке, сохраните версию Python, адрес целевого окружения и очищенный от секретов журнал; выясните, на каком шаге результат отличается от ожидаемого. Не изменяйте глобальный Python ради устранения сбоя проекта.