Офлайн-сборка Python в EXE для Windows: зависимости, PyInstaller, Inno Setup

Практическое руководство для разработчиков и системных администраторов, которым необходимо собрать Windows-приложение на компьютере без доступа к интернету.

При разработке Python-приложений иногда возникает необходимость собрать исполняемый файл .exe на компьютере, где нет доступа к интернету. Такая ситуация встречается в закрытых корпоративных сетях, на промышленных объектах и рабочих станциях с ограниченным доступом к внешним ресурсам.

Для упаковки Python-приложений в Windows часто используют PyInstaller. Он собирает исходный код, интерпретатор Python и необходимые зависимости в исполняемый файл либо каталог с файлами приложения.

Однако сам PyInstaller также является Python-пакетом и зависит от других компонентов. При установке ему могут потребоваться дополнительные библиотеки, а во время сборки он анализирует импорты и ищет необходимые модули, бинарные библиотеки и ресурсы.

Если компьютер не подключён к интернету, стандартная установка через pip install pyinstaller может завершиться ошибкой: пакет или одна из его зависимостей отсутствует в локальной среде.

Решение — заранее подготовить полный комплект зависимостей на другой машине с интернетом, проверить его в изолированном окружении и только после успешной проверки перенести на целевой компьютер.

В этой статье рассмотрим весь процесс на примере приложения path_convertor, Python 3.13 и PyInstaller.

Основной принцип: сначала подготовить и проверить сборку в офлайн-режиме, затем переносить комплект на рабочую машину. Это позволяет обнаружить отсутствующие пакеты и проблемы совместимости до начала работы в закрытом контуре.

Процесс состоит из двух основных этапов.

Этап 1. Подготовка на машине с интернетом

1. Подготовить Windows, совместимую с целевой системой.
2. Установить подходящую версию Python.
3. Создать чистое виртуальное окружение.
4. Установить PyInstaller и зависимости приложения.
5. Зафиксировать версии пакетов.
6. Скачать все необходимые дистрибутивы в отдельный каталог.
7. Создать новое чистое окружение и проверить установку из локального каталога без интернета.
8. Выполнить тестовую сборку и проверить готовый EXE.
9. Подготовить комплект для переноса.

Этап 2. Сборка на целевом компьютере

1. Перенести исходники и проверенный комплект пакетов.
2. Создать новое виртуальное окружение.
3. Установить зависимости только из локального каталога.
4. Проверить окружение.
5. Собрать приложение.
6. Запустить приложение и проверить его работу.
7. При необходимости создать установщик с помощью Inno Setup.

Таким образом, на целевом компьютере не требуется скачивать Python-пакеты из интернета.

Для сборки Windows-приложения желательно использовать Windows той же версии и архитектуры, что и на целевом компьютере.

На совместимость влияют:

• версия Windows;
• архитектура операционной системы — x64 или x86;
• версия и архитектура Python;
• версии PyInstaller и сторонних пакетов;
• системные библиотеки и компоненты Windows.

PyInstaller не является универсальным инструментом кросс-компиляции для любых операционных систем. Если требуется Windows EXE, надёжнее выполнять сборку непосредственно в Windows. Подробнее это описано в документации PyInstaller.

Оптимальный вариант — отдельная виртуальная машина с нужной версией Windows. На ней можно подготовить чистую среду, не затрагивая рабочую систему.

Если виртуальную машину создать нельзя, используйте отдельное виртуальное окружение Python. Оно изолирует установленные Python-пакеты, хотя не изолирует системные DLL, переменные среды и другие компоненты Windows.

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

3.1. Проверяем установленный Python

На машине с интернетом откройте PowerShell и выполните:

py -0p
py -3.13 --version

Первая команда показывает доступные установки Python, вторая проверяет наличие Python 3.13.

Если целевой компьютер использует Python 3.13 x64, подготовительная машина должна использовать совместимую версию и архитектуру.

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

3.2. Подготавливаем каталог проекта

Пример структуры проекта:

path_convertor_win/
├── path_convertor.py
├── icon64.ico
├── LICENSE-2_0.txt
├── setup.iss
├── requirements-build.txt
├── wheelhouse/
├── build/
└── dist/

Назначение каталогов:

• wheelhouse — локальный комплект Python-пакетов;
• build — промежуточные файлы PyInstaller;
• dist — результат сборки;
• requirements-build.txt — список необходимых пакетов и их версий;
• setup.iss — сценарий создания установщика Inno Setup.

Перейдите в каталог проекта и создайте каталог пакетов:

Set-Location "C:\syst\python\deploy\path_convertor_win"

New-Item -ItemType Directory -Force .\wheelhouse

Путь приведён в качестве примера для path_convertor. На другой машине используйте фактическое расположение проекта.

3.3. Создаём виртуальное окружение

Выполните:

py -3.13 -m venv .venv

Активируйте окружение:

.\.venv\Scripts\Activate.ps1

Проверьте, какой интерпретатор используется:

python --version
python -c "import sys; print(sys.executable)"
python -m pip --version

Все последующие команды установки должны выполняться в этом окружении.

Использование python -m pip предпочтительнее отдельной команды pip: это уменьшает вероятность установки пакетов не в ту версию Python.

Перед скачиванием пакетов необходимо выяснить, что именно требуется проекту.

Есть два основных типа зависимостей:

1. Зависимости самого приложения.
2. Зависимости инструментов сборки, в частности PyInstaller.

4.1. Зависимости приложения

Изучите исходный код и существующие файлы зависимостей проекта.

Например, стандартные модули Python:

import os
import sys
import tkinter

не нужно скачивать через pip, поскольку они входят в стандартную библиотеку Python.

Если приложение использует сторонние библиотеки, их нужно установить и включить в список зависимостей.

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

4.2. Зависимости PyInstaller

PyInstaller использует собственные Python-пакеты. В зависимости от версии и платформы среди них могут быть:

• altgraph;
• packaging;
• pyinstaller-hooks-contrib;
• pywin32-ctypes;
• setuptools;
• pefile — при соответствующих платформенных условиях.

Конкретный состав зависит от версии PyInstaller и её метаданных. Поэтому лучше не составлять список вручную, а поручить разрешение зависимостей pip.

Создайте файл requirements-build.txt:

PyInstaller==6.11.1

Версия 6.11.1 используется здесь как пример из рассматриваемой сборки. Для другого проекта зафиксируйте версию, которая была проверена и подходит для используемой версии Python.

Если приложение использует сторонние библиотеки, добавьте их в этот же файл. Например:

PyInstaller==6.11.1
requests==2.32.3

requests в примере не является обязательной зависимостью PyInstaller. Добавлять её нужно только в том случае, если приложение действительно использует эту библиотеку.

Фиксация версий обеспечивает воспроизводимость: при повторной подготовке комплекта pip не будет произвольно выбирать более новые выпуски пакетов.

Для скачивания пакетов используется команда pip download. Она загружает дистрибутивы пакетов и их зависимости, не устанавливая их в окружение.

Официальная документация: pip download.

Убедитесь, что активировано подготовленное виртуальное окружение, затем выполните:

python -m pip download `
    --dest .\wheelhouse `
    -r .\requirements-build.txt

В каталоге wheelhouse появятся скачанные пакеты. Например:

wheelhouse/
├── altgraph-....whl
├── packaging-....whl
├── pefile-....whl
├── pyinstaller-....whl
├── pyinstaller_hooks_contrib-....whl
├── pywin32_ctypes-....whl
└── setuptools-....whl

Фактический набор файлов и версии зависят от выбранного релиза PyInstaller и его зависимостей.

Почему лучше использовать wheel-файлы

Wheel — готовый формат распространения Python-пакетов. При наличии совместимого wheel-файла установка обычно не требует сборки пакета из исходников.

Если pip download скачал исходный архив вместо wheel, установка на целевой машине может потребовать компилятора и дополнительных инструментов.

Для предсказуемой офлайн-установки желательно подготовить совместимые wheel-файлы заранее. Если для какой-либо зависимости готового wheel нет, его можно попробовать создать на подготовительной машине с помощью pip wheel.

Документация: руководство по установке пакетов pip.

Важно: wheelhouse — это комплект установочных дистрибутивов, а не просто копия установленных библиотек из site-packages.

Это ключевой этап, который не следует пропускать.

Сам факт успешного скачивания файлов не гарантирует, что из них можно установить все необходимые пакеты. В каталоге может отсутствовать транзитивная зависимость, нужный вариант wheel-файла или пакет, необходимый для используемой версии Python.

Поэтому до переноса на целевой компьютер нужно проверить, что комплект работает с нуля.

6.1. Подготавливаем чистую машину

Наиболее надёжный вариант — отдельная виртуальная машина с той же версией Windows и Python, что и на целевом компьютере.

На ней не должны быть установлены пакеты проекта или PyInstaller, которые могли бы случайно компенсировать неполноту комплекта.

Перенесите на неё только необходимые материалы:

path_convertor_offline/
├── source/
│   ├── path_convertor.py
│   ├── icon64.ico
│   ├── LICENSE-2_0.txt
│   └── setup.iss
├── wheelhouse/
└── requirements-build.txt

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

Python и другие необходимые инструменты, которые нельзя установить из wheelhouse, должны быть подготовлены заранее.

6.2. Отключаем интернет

Отключите сетевой адаптер контрольной виртуальной машины либо полностью изолируйте её от сети.

Параметр --no-index, который мы будем использовать далее, запрещает pip обращаться к индексу пакетов, но не блокирует сетевые подключения других программ.

Поэтому для настоящей проверки офлайн-сборки интернет должен быть отключён на уровне виртуальной машины или сети.

6.3. Создаём новое виртуальное окружение

Откройте PowerShell в каталоге проекта:

Set-Location "C:\syst\python\deploy\path_convertor_win"

Создайте новое окружение:

py -3.13 -m venv .venv-offline

Проверьте интерпретатор:

.\.venv-offline\Scripts\python.exe --version

.\.venv-offline\Scripts\python.exe -c `
    "import sys; print(sys.executable)"

Почему нельзя ограничиться первоначальным окружением .venv? Потому что PyInstaller и его зависимости уже могли быть установлены там с помощью интернета. Такая среда не доказывает, что комплект wheelhouse самодостаточен.

6.4. Устанавливаем пакеты только из локального каталога

Выполните:

.\.venv-offline\Scripts\python.exe -m pip install `
    --no-index `
    --find-links .\wheelhouse `
    -r .\requirements-build.txt

Здесь:

• --no-index запрещает обращение к внешнему индексу пакетов;
• --find-links .\wheelhouse указывает каталог с локальными дистрибутивами;
• -r .\requirements-build.txt задаёт список устанавливаемых пакетов.

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

Если появляется ошибка No matching distribution found, проверьте состав каталога, версии пакетов, совместимость с Python и наличие подходящих wheel-файлов.

Не следует устранять такую ошибку установкой пакета из системного Python: это скрывает проблему, а не исправляет её.

6.5. Проверяем установленные зависимости

Выполните:

.\.venv-offline\Scripts\python.exe -m pip check

Команда проверяет согласованность установленных Python-пакетов.

Затем проверьте запуск PyInstaller:

.\.venv-offline\Scripts\python.exe -m PyInstaller --version

Если приложение использует сторонние библиотеки, дополнительно проверьте их импорт. Например, для проекта, использующего requests:

.\.venv-offline\Scripts\python.exe -c `
    "import requests; print(requests.__version__)"

Выполнять этот пример нужно только при наличии requests в зависимостях проекта.

6.6. Выполняем контрольную офлайн-сборку

При отключённом интернете выполните сборку приложения из нового окружения:

.\.venv-offline\Scripts\python.exe -m PyInstaller `
    --noconfirm `
    --clean `
    --onefile `
    --windowed `
    --log-level DEBUG `
    --specpath build `
    --icon "$PWD\icon64.ico" `
    --name path_convertor `
    path_convertor.py 2>&1 |
    Tee-Object -FilePath .\build-offline.log

Команда рассчитана на запуск из каталога, в котором находятся path_convertor.py и icon64.ico. Если исходники лежат в каталоге source, сначала перейдите в него или скорректируйте пути в команде.

После завершения проверьте результат:

Test-Path .\dist\path_convertor.exe

Если возвращается True, EXE создан.

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

Если сборка завершилась ошибкой, изучите build-offline.log, исправьте комплект на подготовительной машине и повторите всю проверку.

6.7. Что считается успешной проверкой

Перед переносом на целевой компьютер должны выполняться все условия:

• новое виртуальное окружение создано с нуля;
• все зависимости установлены из wheelhouse;
• во время установки интернет отключён;
• pip check не сообщает о проблемах;
• PyInstaller запускается;
• сборка завершается без критических ошибок;
• EXE создан;
• приложение запускается и выполняет основные функции.

Если планируется создание установщика Inno Setup, его тоже необходимо отдельно проверить в офлайн-режиме.

После успешной контрольной сборки комплект можно считать проверенным для дальнейшего переноса. Если на целевом компьютере отличаются версия Windows или набор системных компонентов, окончательный тест всё равно следует выполнить там.

Подробные логи помогают выяснить, какие модули, библиотеки и ресурсы обнаруживает PyInstaller, а также на каком этапе возникает ошибка.

Пример команды сборки с подробным журналом:

python -m PyInstaller `
    --noconfirm `
    --clean `
    --onefile `
    --windowed `
    --log-level DEBUG `
    --specpath build `
    --icon "$PWD\icon64.ico" `
    --name path_convertor `
    path_convertor.py 2>&1 |
    Tee-Object -FilePath .\build.log

Основные параметры:

• --noconfirm — не запрашивать подтверждение перезаписи;
• --clean — очистить кэш и временные данные перед сборкой;
• --onefile — создать один исполняемый файл;
• --windowed — не открывать консоль для GUI-приложения;
• --log-level DEBUG — включить подробный журнал;
• --specpath build — хранить .spec в отдельном каталоге;
• Tee-Object — сохранить журнал в файл и одновременно показывать его в консоли.

На что обращать внимание

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

Поиск DLL. Сообщения о бинарных библиотеках помогают определить, какие зависимости пытается обнаружить PyInstaller. Однако нельзя автоматически скачивать каждый упомянутый файл.

Завершение сборки. Важно проверить, завершилась ли операция успешно и был ли создан ожидаемый EXE.

Файл .spec. Он описывает настройки сборки и включаемые модули, бинарные файлы и ресурсы. Его можно использовать для настройки повторяемой сборки. Подробнее: Spec Files.

Логи помогают исследовать состав приложения, но не заменяют проверку зависимостей средствами pip и тестовую сборку без интернета.

Во время сборки path_convertor появилось предупреждение:

WARNING: Library not found; could not resolve
'api-ms-win-crt-Filesystem-11-1-0.dll',
dependency of '...\Python313\python313.dll'

Такое сообщение не означает автоматически, что необходимо найти и вручную скачать DLL.

Некоторые имена api-ms-win-* относятся к механизму API-set Windows. Они не всегда соответствуют обычным библиотекам, которые должны находиться в каталоге приложения. Результат также зависит от версии Windows, Python и установленных системных компонентов.

Правильный порядок действий:

1. Дождаться завершения сборки.
2. Проверить, создан ли EXE.
3. Запустить приложение на машине сборки.
4. Проверить его на целевой Windows.
5. Если запуск не удался, исследовать фактическую ошибку и проверить необходимые системные компоненты.

Для предварительной проверки конкретного файла можно выполнить:

Test-Path "$env:WINDIR\System32\api-ms-win-crt-filesystem-l1-1-0.dll"

Отрицательный результат сам по себе не доказывает, что приложение не сможет работать.

Если действительно отсутствует необходимый компонент Microsoft Visual C++ Runtime или Universal CRT, используйте официальный установщик Microsoft, совместимый с целевой Windows. В закрытой сети его необходимо заранее получить из доверенного источника.

Не следует скачивать отдельные DLL с неизвестных сайтов или копировать системные библиотеки наугад в каталог приложения.

После успешной контрольной сборки подготовьте комплект для переноса:

path_convertor_offline/
├── source/
│   ├── path_convertor.py
│   ├── icon64.ico
│   ├── LICENSE-2_0.txt
│   └── setup.iss
├── wheelhouse/
├── requirements-build.txt
└── BUILD_WINDOWS.md

При необходимости включите:

• совместимый установщик Python, если интерпретатор ещё не установлен;
• установщик Inno Setup;
• дополнительные ресурсы проекта;
• контрольные суммы файлов;
• инструкцию сборки.

Если перенос выполняется через USB-носитель или другой промежуточный канал, убедитесь, что все файлы скопированы корректно. При строгих требованиях безопасности рекомендуется заранее сформировать SHA-256-суммы и проверить их после переноса.

Виртуальное окружение .venv с подготовительной машины переносить не рекомендуется. Оно может содержать абсолютные пути и привязки к конкретному интерпретатору. На целевой машине лучше создать окружение заново.

Откройте PowerShell и перейдите в каталог проекта:

Set-Location "C:\syst\python\deploy\path_convertor_win"

Создайте виртуальное окружение:

py -3.13 -m venv .venv

Установите пакеты из локального каталога:

.\.venv\Scripts\python.exe -m pip install `
    --no-index `
    --find-links .\wheelhouse `
    -r .\requirements-build.txt

Проверьте зависимости:

.\.venv\Scripts\python.exe -m pip check

Проверьте PyInstaller:

.\.venv\Scripts\python.exe -m PyInstaller --version

Если установка завершается ошибкой, проверьте:

• все ли файлы были перенесены;
• присутствует ли требуемая версия пакета в wheelhouse;
• подходит ли пакет для установленной версии Python;
• соответствует ли wheel-файл архитектуре и платформе;
• указаны ли необходимые зависимости в requirements-build.txt.

Не исправляйте неполный комплект случайной установкой пакетов из системного Python.

Для проекта path_convertor выполните из корневого каталога проекта:

.\.venv\Scripts\python.exe -m PyInstaller `
    --noconfirm `
    --onefile `
    --windowed `
    --specpath build `
    --icon "$PWD\icon64.ico" `
    --name path_convertor `
    path_convertor.py

Параметр --specpath build сохраняет создаваемый .spec-файл отдельно и позволяет не перезаписывать существующий path_convertor.spec в корне проекта.

После успешной сборки EXE должен находиться здесь:

dist\path_convertor.exe

Проверить наличие файла можно командой:

Test-Path .\dist\path_convertor.exe

Если результат — True, файл существует. Теперь запустите его:

Start-Process .\dist\path_convertor.exe

Проверьте основные функции приложения, чтение и запись файлов, обработку ошибок и преобразование путей Windows и Linux.

Для диагностики проблем на этапе разработки можно временно убрать --windowed, чтобы видеть сообщения консоли.

PyInstaller создаёт исполняемое приложение. Если требуется распространять его через установщик, необходимо выполнить отдельный этап с помощью Inno Setup.

Сам Inno Setup не устанавливается через pip. Его установщик и необходимые инструменты должны быть подготовлены заранее.

Проверьте файл setup.iss и убедитесь, что все пути соответствуют фактической структуре проекта. Если используются относительные пути, компиляцию следует выполнять из ожидаемого каталога или явно настроить пути в сценарии.

После компиляции установщик может находиться, например, по следующему пути:

Output\PathConvertorSetup.exe

Проверьте наличие файла, установите приложение на тестовой машине и убедитесь, что установщик содержит все необходимые ресурсы, правильно создаёт ярлыки и запускает приложение.

Если конечная машина полностью изолирована, контрольную компиляцию setup.iss также следует провести заранее без интернета.

Повреждённые метаданные Python-пакетов

В ходе подготовки path_convertor обнаружилась ошибка в метаданных PyInstaller: требование для pefile было записано некорректно, и pip не мог правильно разобрать зависимость.

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

Рекомендуемый порядок действий:

1. Повторно получить пакет из доверенного источника.
2. Сверить версию и контрольную сумму, если она доступна.
3. Создать новое чистое окружение.
4. Повторить установку зависимостей.
5. Проверить результат через pip check.

Ручное исправление METADATA внутри site-packages может служить временным обходным путём для диагностики, но не исправляет исходный дистрибутив. Если такой способ применялся, необходимо задокументировать изменения и повторно проверить сборку в чистом окружении.

Если приложение нужно собирать регулярно, целесообразно оформить процедуру как небольшой регламент.

Рекомендуется хранить вместе с проектом:

• requirements-build.txt с зафиксированными версиями;
• исходники и ресурсы приложения;
• каталог wheelhouse;
• инструкцию сборки;
• версии Python, PyInstaller и Inno Setup;
• журнал последней успешной сборки;
• сведения о версии Windows и архитектуре;
• контрольные суммы переносимых файлов.

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

Не стоит автоматически обновлять пакеты при каждой сборке. Лучше использовать проверенные версии, а обновления внедрять контролируемо.

Перед переносом

• [ ] Подготовительная машина соответствует целевой Windows.
• [ ] Используются подходящие версия и архитектура Python.
• [ ] Создано чистое виртуальное окружение.
• [ ] Версии зависимостей зафиксированы.
• [ ] Пакеты скачаны в wheelhouse.
• [ ] Создано новое чистое окружение для проверки.
• [ ] Установка из wheelhouse успешно выполнена без интернета.
• [ ] pip check не сообщает о проблемах.
• [ ] PyInstaller запускается.
• [ ] Выполнена контрольная офлайн-сборка.
• [ ] EXE создан и протестирован.
• [ ] Inno Setup и другие необходимые инструменты подготовлены заранее.
• [ ] Файлы проверены после переноса.

На целевом компьютере

• [ ] Python установлен и совместим с подготовленным комплектом.
• [ ] Виртуальное окружение создано заново.
• [ ] Пакеты установлены только из локального каталога.
• [ ] pip check не сообщает об ошибках.
• [ ] PyInstaller запускается.
• [ ] EXE успешно собран.
• [ ] Приложение протестировано на целевой Windows.
• [ ] При необходимости собран и проверен установщик.

Сборка Python-приложения на компьютере без интернета вполне реализуема, если заранее подготовить совместимое окружение и полный комплект зависимостей.

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

Связка из виртуального окружения, pip download, установки через --no-index --find-links и контрольной офлайн-сборки позволяет заранее выявить большинство проблем с зависимостями.

При этом Python-пакеты — только часть процесса. Нужно учитывать системные библиотеки Windows, архитектуру, совместимость версий, дополнительные ресурсы и внешние инструменты, например Inno Setup.

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