Использование Python в Windows

4.1.1. Этапы установки

Для загрузки доступны четыре установщика Python 3.13 — по два для 32-разрядной и 64-разрядной версий интерпретатора. Веб-установщик представляет собой небольшую начальную загрузку и автоматически загружает необходимые компоненты по мере необходимости. Автономный установщик содержит компоненты, необходимые для установки по умолчанию, и требует подключения к Интернету только для дополнительных функций. Другие способы избежать загрузки во время установки описаны в разделе Установка без загрузки.

После запуска установщика можно выбрать один из двух вариантов:

Если выбрать «Install Now» («Установить сейчас»):

• Права администратора не потребуются (кроме случаев, когда необходимо обновить системную библиотеку C Runtime или установить Программу запуска Python для Windows для всех пользователей)
• Python будет установлен в каталог вашего пользователя
• Программа запуска Python для Windows будет установлена в соответствии с параметром в нижней части первой страницы
• Будут установлены стандартная библиотека, набор тестов, программа запуска и pip
• Если этот параметр выбран, каталог установки будет добавлен в вашу PATH
• Ярлыки будут видны только текущему пользователю

При выборе «Customize installation» («Настроить установку») можно выбрать устанавливаемые функции, расположение установки, другие параметры и действия после установки. Чтобы установить отладочные символы или двоичные файлы, необходимо выбрать этот вариант.

Чтобы выполнить установку для всех пользователей, выберите «Customize installation» («Настроить установку»). В этом случае:

• Может потребоваться предоставить учётные данные администратора или подтвердить запрос
• Python будет установлен в каталог Program Files
• Программа запуска Python для Windows будет установлена в каталог Windows
• Во время установки можно выбрать дополнительные функции
• Стандартную библиотеку можно предварительно скомпилировать в байт-код
• Если этот параметр выбран, каталог установки будет добавлен в системную PATH
• Ярлыки будут доступны всем пользователям

4.1.2. Снятие ограничения MAX_PATH

Исторически Windows ограничивала длину путей 260 символами. Это означало, что пути большей длины не разрешались и приводили к ошибкам.

В последних версиях Windows это ограничение можно увеличить примерно до 32 000 символов. Администратору необходимо активировать групповую политику «Enable Win32 long paths» («Включить длинные пути Win32») или задать LongPathsEnabled значение 1 в разделе реестра HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem.

Это позволяет функции open(), модулю os и большинству других средств работы с путями принимать и возвращать пути длиной более 260 символов.

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

4.1.3. Установка без пользовательского интерфейса

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

Установщику можно передать следующие параметры (их список можно получить, запустив установщик с /?):

Все остальные параметры передаются как name=value, где значение обычно равно 0 для отключения функции, 1 для её включения или представляет собой путь. Полный список доступных параметров приведён ниже.

Например, чтобы выполнить установку Python по умолчанию для всей системы без отображения интерфейса, можно использовать следующую команду (из командной строки, запущенной с повышенными правами):

python-3.9.0.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0

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

python-3.9.0.exe InstallAllUsers=0 Include_launcher=0 Include_test=0
    SimpleInstall=1 SimpleInstallDescription="Just for me, no test suite."

(Обратите внимание: если не устанавливать программу запуска, не будут созданы и ассоциации файлов. Этот вариант рекомендуется только для установки для отдельного пользователя, если программа запуска уже установлена в рамках системной установки.)

Перечисленные выше параметры также можно указать в файле с именем unattend.xml, расположенном рядом с исполняемым файлом. В этом файле задаётся список параметров и значений. Если значение задано как атрибут, оно будет преобразовано в число, если это возможно. Значения, указанные в виде текста элемента, всегда остаются строками. В этом примере файла заданы те же параметры, что и в предыдущем примере:

<Options>
    <Option Name="InstallAllUsers" Value="no" />
    <Option Name="Include_launcher" Value="0" />
    <Option Name="Include_test" Value="no" />
    <Option Name="SimpleInstall" Value="yes" />
    <Option Name="SimpleInstallDescription">Just for me, no test suite</Option>
</Options>

4.1.4. Установка без загрузки

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

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

python-3.9.0.exe /layout [optional target directory]

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

4.1.5. Изменение установки

После установки Python можно добавлять или удалять функции с помощью инструмента «Программы и компоненты», входящего в состав Windows. Выберите запись Python и нажмите «Удалить/Изменить», чтобы открыть установщик в режиме обслуживания.

Пункт «Изменить» позволяет добавлять или удалять функции, меняя флажки: флажки, состояние которых не изменено, не приведут к установке или удалению компонентов. В этом режиме нельзя изменить некоторые параметры, например каталог установки. Чтобы изменить их, необходимо полностью удалить Python, а затем установить его заново.

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

Пункт «Удалить» полностью удалит Python, за исключением Программы запуска Python для Windows, для которой в разделе «Программы и компоненты» предусмотрена отдельная запись.

4.1.6. Установка двоичных файлов со свободной многопоточностью

Чтобы установить предварительно собранные двоичные файлы с включённой свободной многопоточностью (см. PEP 703), выберите «Customize installation» («Настроить установку»). На второй странице параметров есть флажок «Download free-threaded binaries» («Загрузить двоичные файлы со свободной многопоточностью»).

При выборе этого параметра дополнительные двоичные файлы будут загружены и установлены в то же расположение, что и основная установка Python. Основной исполняемый файл называется python3.13t.exe, а другие двоичные файлы получают суффикс t или полный суффикс ABI. Исходные файлы Python и входящие в комплект сторонние зависимости используются совместно с основной установкой.

Версия со свободной многопоточностью регистрируется как обычная установка Python с тегом 3.13t (с суффиксом -32 или -arm64, как обычно для этих платформ). Это позволяет инструментам обнаруживать её, а Программе запуска Python для Windows — поддерживать py.exe -3.13t. Обратите внимание: программа запуска интерпретирует py.exe -3 (или шебанг python3) как «последнюю установленную версию 3.x» и отдаёт предпочтение двоичным файлам со свободной многопоточностью перед обычными, тогда как py.exe -3.13 этого не делает. Если вы используете краткую форму параметра, возможно, сейчас вам лучше не устанавливать двоичные файлы со свободной многопоточностью.

Чтобы указать параметр установки в командной строке, используйте Include_freethreaded=1. Инструкции по предварительной загрузке дополнительных двоичных файлов для автономной установки см. в разделе Установка без загрузки. Параметры включения отладочных символов и двоичных файлов также применяются к сборкам со свободной многопоточностью.

Двоичные файлы со свободной многопоточностью также доступны на nuget.org.

4.2.1. Известные проблемы

>>> import os
>>> test_file = 'C:\\Users\\example\\AppData\\Local\\test.txt'
>>> os.path.realpath(test_file)
'C:\\Users\\example\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.8_qbz5n2kfra8p0\\LocalCache\\Local\\test.txt'

4.3.1. Пакеты со свободной многопоточностью

Пакеты, содержащие двоичные файлы со свободной многопоточностью, называются python-freethreaded для 64-разрядной версии, pythonx86-freethreaded для 32-разрядной версии и pythonarm64-freethreaded для версии ARM64. Эти пакеты содержат точки входа python3.13t.exe и python.exe, обе из которых работают со свободной многопоточностью.

4.4.1. Приложение на Python

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

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

Более простой подход — предоставить пакетный файл или созданный ярлык, который непосредственно вызывает python.exe или pythonw.exe с необходимыми аргументами командной строки. В этом случае приложение будет выглядеть как Python, а не как программа со своим настоящим именем; пользователям может быть трудно отличить его от других запущенных процессов Python или ассоциаций файлов.

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

4.4.2. Встраивание Python

Приложения, написанные на машинном коде, часто нуждаются в каком-либо языке сценариев; для этой цели можно использовать встраиваемый дистрибутив Python. Как правило, большая часть приложения написана на машинном коде, а отдельная его часть либо вызывает python.exe, либо напрямую использует python3.dll. В обоих случаях достаточно распаковать встраиваемый дистрибутив во вложенный каталог установки приложения, чтобы получить загружаемый интерпретатор Python.

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

4.6.1. Отступление: настройка переменных среды

В Windows переменные среды можно настроить постоянно на уровне пользователя и системы или временно в командной строке.

Чтобы временно задать переменные среды, откройте командную строку и используйте команду set:

C:\>set PATH=C:\Program Files\Python 3.9;%PATH%
C:\>set PYTHONPATH=%PYTHONPATH%;C:\My_python_lib
C:\>python

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

Если заключить имя переменной в знаки процента, её текущее значение будет подставлено, что позволяет добавить новое значение в начало или конец. Добавление каталога с файлом python.exe в начало переменной PATH — распространённый способ обеспечить запуск нужной версии Python.

Чтобы навсегда изменить переменные среды по умолчанию, нажмите кнопку «Пуск» и выполните поиск по запросу «изменение переменных среды» либо откройте свойства системы, выберите Дополнительные параметры системы и нажмите кнопку Переменные среды. В этом диалоговом окне можно добавлять и изменять переменные пользователя и системы. Для изменения системных переменных необходим доступ без ограничений к компьютеру (то есть права администратора).

4.6.2. Поиск исполняемого файла Python

Помимо запуска интерпретатора Python через автоматически созданный ярлык в меню «Пуск», вы можете запускать Python из командной строки. Установщик позволяет настроить это.

На первой странице установщика можно выбрать параметр «Add Python to PATH», чтобы установщик добавил путь установки в PATH. Также добавляется расположение каталога Scripts\. Благодаря этому для запуска интерпретатора можно ввести команду python, а для запуска установщика пакетов — pip. Это также позволяет запускать сценарии с параметрами командной строки; см. документацию Командная строка.

Если вы не включили этот параметр при установке, можно снова запустить установщик, выбрать «Modify» и включить его. В качестве альтернативы можно вручную изменить PATH, следуя указаниям в разделе Отступление: настройка переменных среды. Необходимо добавить каталог установки Python в переменную среды PATH, отделив его точкой с запятой от остальных записей. Пример такой переменной (предполагается, что первые две записи уже существуют):

C:\WINDOWS\system32;C:\WINDOWS;C:\Program Files\Python 3.9

4.8.1. Начало работы

py

py -3.7

py -2

'py' is not recognized as an internal or external command,
operable program or batch file.

py --list

# Select any '3.*' tagged runtime
py -V:3

# Select any 'PythonCore' released runtime
py -V:PythonCore/

# Select PythonCore's latest Python 3 runtime
py -V:PythonCore/3

#! python
import sys
sys.stdout.write("hello from Python %s\n" % (sys.version,))

py hello.py

#! python3

4.8.2. Строки шебанга

Если первая строка файла сценария начинается с #!, она называется строкой «шебанга». Linux и другие Unix-подобные операционные системы поддерживают такие строки на уровне системы; обычно они используются для указания способа запуска сценария. Это средство запуска позволяет использовать те же возможности со сценариями Python в Windows, как показано в приведённых выше примерах.

Чтобы строки шебанга в сценариях Python были переносимыми между Unix и Windows, средство запуска поддерживает несколько «виртуальных» команд для указания нужного интерпретатора. Поддерживаются следующие виртуальные команды:

• /usr/bin/env
• /usr/bin/python
• /usr/local/bin/python
• python

Например, если первая строка сценария начинается с

#! /usr/bin/python

Будет найден и использован интерпретатор Python по умолчанию или интерпретатор активной виртуальной среды. Многие сценарии Python, написанные для Unix, уже содержат эту строку, поэтому средство запуска сможет использовать их без изменений. Если вы пишете новый сценарий в Windows, который может пригодиться и в Unix, используйте одну из строк шебанга, начинающихся с /usr.

К любой из перечисленных выше виртуальных команд можно добавить конкретную версию (только основную либо основную и дополнительную). Кроме того, можно запросить 32-разрядную версию, добавив «-32» после дополнительной версии. Например, /usr/bin/python3.7-32 запросит 32-разрядную версию Python 3.7. Если активна виртуальная среда, версия будет проигнорирована и будет использоваться эта среда.

У формы строки шебанга /usr/bin/env есть ещё одно особое свойство. Прежде чем искать установленные интерпретаторы Python, эта форма ищет в исполняемом файле PATH исполняемый файл Python с именем, заданным первым аргументом. Это соответствует поведению программы Unix env, которая выполняет поиск PATH. Если исполняемый файл, соответствующий первому аргументу после команды env, не найден, но аргумент начинается с python, он будет обработан так же, как и другие виртуальные команды. Чтобы пропустить поиск в PATH, можно задать переменную среды PYLAUNCHER_NO_SEARCH_PATH (любым значением).

Для строк шебанга, не соответствующих ни одному из этих шаблонов, поиск выполняется в разделе [commands] файла .INI средства запуска. Это можно использовать для обработки определённых команд способом, подходящим для вашей системы. Имя команды должно состоять из одного аргумента (в исполняемом файле шебанга не должно быть пробелов), а подставляемым значением является полный путь к исполняемому файлу (дополнительные аргументы, указанные в .INI-файле, будут включены в имя файла в кавычках).

[commands]
/bin/xpython=C:\Program Files\XPython\python.exe

Команды, не найденные в .INI-файле, рассматриваются как пути к исполняемым файлам Windows, являющиеся абсолютными или относительными к каталогу, содержащему файл сценария. Это удобно для сценариев, предназначенных только для Windows, например созданных установщиком, поскольку такое поведение несовместимо с оболочками Unix. Эти пути можно заключать в кавычки и дополнять несколькими аргументами; после них будут добавлены путь к сценарию и любые дополнительные аргументы.

4.8.3. Аргументы в строках шебанга

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

#! /usr/bin/python -v

Python будет запущен с параметром -v

4.8.4. Настройка

[defaults]
python=3.7

[defaults]
python=3
python3=3.7

4.8.5. Диагностика

Если переменной среды PYLAUNCHER_DEBUG присвоено любое значение, средство запуска выведет диагностические сведения в stderr (то есть в консоль). Несмотря на то, что эти сведения одновременно многословны и лаконичны, они должны помочь выяснить, какие версии Python были найдены, почему была выбрана конкретная версия и какая именно команда командной строки использовалась для запуска целевого Python. Эта возможность предназначена в первую очередь для тестирования и отладки.

4.8.6. Пробный запуск

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

4.8.7. Установка по запросу

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

Дополнительная переменная PYLAUNCHER_ALWAYS_INSTALL заставляет средство запуска всегда пытаться установить Python, даже если он уже обнаружен. Эта возможность предназначена главным образом для тестирования (и её следует использовать вместе с PYLAUNCHER_DRYRUN).

4.8.8. Коды возврата

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

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

4.10.1. PyWin32

Модуль PyWin32, созданный Марком Хаммондом, представляет собой набор модулей для расширенной поддержки возможностей Windows. В него входят средства для работы с:

• Component Object Model (COM)
• вызовами Win32 API
• реестром
• журналом событий
• Microsoft Foundation Classes (MFC) для создания пользовательских интерфейсов

PythonWin — пример приложения MFC, поставляемый с PyWin32. Это встраиваемая интегрированная среда разработки со встроенным отладчиком.

4.10.2. cx_Freeze

cx_Freeze упаковывает скрипты Python в исполняемые программы Windows (файлы *.exe). После этого приложение можно распространять, не требуя от пользователей установки Python.