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

4.1.1. Установка

Диспетчер установки Python можно установить из приложения Microsoft Store или загрузить и установить с сайта python.org/downloads. Обе версии идентичны.

Чтобы установить приложение через Store, просто нажмите «Установить». После завершения установки откройте терминал и введите python, чтобы начать работу.

Чтобы установить файл, загруженный с сайта python.org, дважды щёлкните его и выберите «Установить» либо выполните команду Add-AppxPackage <path to MSIX> в Windows Powershell.

После установки должны стать доступны команды python, py и pymanager. Если у вас уже установлены версии Python или вы изменяли переменную PATH, возможно, потребуется удалить их или отменить внесённые изменения. Дополнительные сведения об исправлении неработающих команд см. в разделе Устранение неполадок.

При первой установке среды выполнения может появиться запрос на добавление каталога в переменную PATH. Это необязательно, если вы предпочитаете использовать команду py, но эта возможность предлагается тем, кто хочет, чтобы был доступен полный набор псевдонимов (например, python3.14.exe). По умолчанию каталог будет %LocalAppData%\Python\bin, но администратор может изменить его. Нажмите «Пуск» и найдите «Изменение переменных среды для вашей учётной записи», чтобы открыть страницу системных настроек и добавить путь.

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

Диспетчер установки Python будет автоматически обновляться до новых выпусков. Это не влияет на установленные среды выполнения Python. Удаление диспетчера установки Python не приводит к удалению сред выполнения Python.

Если в вашей среде невозможно установить MSIX, например, вы используете программное обеспечение для автоматизированного развёртывания, которое его не поддерживает, или работаете с Windows Server 2019, дополнительную информацию см. ниже в разделе Расширенная установка.

4.1.2. Основы использования

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

Во всех случаях, связанных с несколькими версиями среды выполнения, рекомендуется использовать команду py. Её можно использовать везде вместо python или более старого средства запуска py.exe. По умолчанию py ведёт себя так же, как python, но также позволяет выбирать конкретную версию с помощью параметров командной строки и управлять установками с помощью подкоманд. Они подробно описаны ниже.

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

Для каждой из этих команд также существует оконная версия, которая не создаёт окно консоли. Это команды pyw, pythonw и pywmanager. Также включена команда python3, имитирующая команду python. Она предназначена для перехвата случайного использования типичной команды POSIX в Windows, но не рассчитана на широкое использование и не рекомендуется к применению.

Чтобы запустить среду выполнения по умолчанию, выполните python или py с аргументами, которые нужно передать среде выполнения (например, файлами скриптов или запускаемым модулем):

$> py
...
$> python my-script.py
...
$> py -m this
...

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

Для запуска конкретной среды выполнения команда py принимает параметр -V:<TAG>. Этот параметр необходимо указывать перед всеми остальными. Тег — это часть или полное обозначение среды выполнения; для сред от команды CPython он выглядит как номер версии, возможно, с указанием платформы. Для совместимости V: можно опустить, если тег относится к официальному выпуску и начинается с 3.

$> py -V:3.14 ...
$> py -V:3-arm64 ...

Для сред выполнения от других дистрибьюторов может потребоваться указать также компанию. Её следует отделить от тега косой чертой (/ или \), при этом можно указать любой префикс полного названия. Название компании можно не указывать, если оно PythonCore; тег можно не указывать (но косую черту — нельзя), если требуется последний выпуск от определённой компании.

$> py -V:Distributor\1.0 ...
$> py -V:distrib/ ...

Если версия не указана, но передан файл скрипта, скрипт будет проверен на наличие строки shebang. Это специальный формат первой строки файла, позволяющий переопределить команду. Дополнительные сведения см. в разделе Строки shebang. Если строки shebang нет или её не удаётся обработать, скрипт будет запущен с использованием среды выполнения по умолчанию.

Если вы работаете в активном виртуальном окружении, не запрашивали конкретную версию и в скрипте нет строки shebang, средой выполнения по умолчанию будет это виртуальное окружение. В таком случае команда python, вероятно, уже была переопределена, поэтому эти проверки не выполнялись. Однако такое поведение позволяет взаимозаменяемо использовать команду py.

Если среды выполнения не установлены, любая команда запуска попытается установить запрошенную версию и запустить её. Однако после установки любой версии автоматически устанавливать отсутствующую запрошенную версию будут только команды py exec ... и pymanager exec .... Другие варианты команд покажут ошибку и предложат сначала использовать py install.

4.1.3. Справка по командам

Команда py help выведет полный список поддерживаемых команд и их параметров. Для отображения справки к любой команде можно передать ей параметр -? или передать её имя команде py help.

$> py help
$> py help install
$> py install /?

Все команды поддерживают некоторые общие параметры, которые будут показаны командой py help. Эти параметры необходимо указывать после любой подкоманды. Параметры -v или --verbose увеличивают объём выводимой информации, а -vv дополнительно увеличивает его для отладки. Параметры -q или --quiet сокращают вывод, а -qq сокращает его ещё сильнее.

Параметр --config=<PATH> позволяет указать файл конфигурации для переопределения сразу нескольких настроек. Дополнительные сведения об этих файлах см. ниже в разделе Конфигурация.

4.1.4. Просмотр списка сред выполнения

$> py list [-f=|--format=<FMT>] [-1|--one] [--online|-s=|--source=<URL>] [<TAG>...]

Список установленных сред выполнения можно просмотреть с помощью команды py list. Можно добавить фильтр в виде одного или нескольких тегов (с указанием компании или без него); каждый тег может содержать префикс <, <=, >= или >, ограничивающий диапазон.

Поддерживается несколько форматов, которые можно указать с помощью параметра --format=<FMT> или -f <FMT>. Доступны форматы table (удобное для пользователя табличное представление), csv (таблица с разделителями-запятыми), json (единый объект JSON), jsonl (отдельный объект JSON для каждого результата), exe (только путь к исполняемому файлу), prefix (только путь к префиксу).

Параметр --one или -1 отображает только один результат. Если среди результатов есть среда выполнения по умолчанию, будет показана она. В противном случае показывается «наилучший» результат (понятие «наилучший» намеренно определено расплывчато, но обычно это самая новая версия). Результат, показанный командой py list --one <TAG>, будет соответствовать среде выполнения, которая была бы запущена командой py -V:<TAG>.

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

Параметр --online является сокращённой формой передачи --source=<URL> с источником по умолчанию. Передача любого из этих параметров запускает поиск в сетевом индексе сред выполнения, доступных для установки. Результат, показанный командой py list --online --one <TAG>, будет соответствовать среде выполнения, которая была бы установлена командой py install <TAG>.

$> py list --online 3.14

Для совместимости со старым средством запуска сохранены команды --list, --list-paths, -0 и -0p (например, py -0p). Они не поддерживают дополнительные параметры и выводят данные в устаревшем формате.

4.1.5. Установка сред выполнения

$> py install [-s=|--source=<URL>] [-f|--force] [-u|--update] [--dry-run] [<TAG>...]

Новые версии среды выполнения можно добавить с помощью команды py install. Можно указать один или несколько тегов; специальный тег default позволяет выбрать значение по умолчанию. Диапазоны при установке не поддерживаются.

Параметр --source=<URL> позволяет переопределить сетевой индекс, используемый для получения сред выполнения. Его можно использовать с автономным индексом, как показано в разделе Автономная установка.

Передача --force приведёт к игнорированию всех кэшированных файлов и удалению существующей установки с заменой на указанную.

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

Передача --dry-run приведёт к формированию вывода и журналов, но не изменит установки.

Передача --refresh обновит все регистрации установленных сред выполнения. Будут созданы заново ярлыки в меню «Пуск», ключи реестра и глобальные псевдонимы (например, python3.14.exe или псевдонимы для любых установленных скриптов). Они автоматически обновляются при установке любой среды выполнения, но после установки пакетов может потребоваться обновить их вручную.

Помимо перечисленных выше параметров, параметр --target распакует среду выполнения в указанную папку вместо обычной установки. Это полезно при встраивании сред выполнения в более крупные приложения. В отличие от обычной установки, py не будет знать о распакованной среде выполнения, а ярлыки в меню «Пуск» и другие ярлыки созданы не будут. Чтобы запустить среду выполнения, выполните основной исполняемый файл непосредственно из целевой папки (обычно это python.exe).

$> py install ... [-t=|--target=<PATH>] <TAG>

Команда py exec установит запрошенную среду выполнения, если она ещё не установлена. Это поведение определяется параметром конфигурации automatic_install (PYTHON_MANAGER_AUTOMATIC_INSTALL), который по умолчанию включён. Если среды выполнения вообще отсутствуют, все команды запуска выполнят автоматическую установку, если это разрешено настройкой конфигурации. Это сделано для удобства новых пользователей, но в целом не следует полагаться на такое поведение вместо команды py exec или явных команд установки.

4.1.6. Автономная установка

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

$> py install --download=<PATH> ... <TAG>...

Параметр --download=<PATH> загрузит пакеты для перечисленных тегов и создаст каталог, содержащий эти пакеты и файл index.json, пригодный для последующей установки. Весь этот каталог можно перенести на компьютер без доступа к сети и использовать для установки одной или нескольких содержащихся в нём сред выполнения:

$> py install --source="<PATH>\index.json" <TAG>...

Диспетчер установки Python можно установить, загрузив установщик и перенеся его на другой компьютер перед установкой.

Кроме того, ZIP-файлы в каталоге автономного индекса можно просто перенести на другой компьютер и распаковать. Такая установка не будет зарегистрирована, поэтому для её запуска необходимо напрямую обращаться к исполняемым файлам в распакованном каталоге. Однако иногда такой подход предпочтительнее, если установить диспетчер установки Python невозможно или неудобно.

Таким образом можно устанавливать и администрировать среды выполнения Python на компьютере без доступа к Интернету.

4.1.7. Удаление сред выполнения

$> py uninstall [-y|--yes] <TAG>...

Среды выполнения можно удалить с помощью команды py uninstall. Необходимо указать один или несколько тегов. Диапазоны здесь не поддерживаются.

Параметр --yes пропускает запрос подтверждения перед удалением.

Вместо передачи тегов по отдельности можно указать параметр --purge. Он удалит все среды выполнения, которыми управляет диспетчер установки Python, а также очистит меню «Пуск», реестр и все кэши загрузок. Среды выполнения, установленные не с помощью диспетчера установки Python, не будут затронуты; вручную созданные файлы конфигурации также останутся без изменений.

$> py uninstall [-y|--yes] --purge

Диспетчер установки Python можно удалить на странице настроек Windows «Установленные приложения». Это не удалит среды выполнения: ими по-прежнему можно будет пользоваться, хотя глобальные команды python и py будут удалены. После повторной установки диспетчера установки Python вы снова сможете управлять этими средами выполнения. Чтобы полностью удалить все среды выполнения Python, перед удалением диспетчера установки Python выполните команду с параметром --purge.

4.1.8. Конфигурация

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

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

Глобальный файл конфигурации может быть настроен администратором и будет считан первым. Пользовательский файл конфигурации хранится в %AppData%\Python\pymanager.json (обратите внимание: это расположение находится в Roaming, а не в Local) и считывается следующим, переопределяя настройки из более ранних файлов. Дополнительный файл конфигурации можно указать с помощью переменной среды PYTHON_MANAGER_CONFIG или параметра командной строки --config (но не обоих одновременно). Эти расположения можно изменить с помощью параметров административной настройки, перечисленных далее.

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

Стандартные параметры конфигурации

Составные имена, разделённые точками, следует помещать во вложенные объекты JSON. Например, list.format следует указать как {"list": {"format": "table"}}.

4.1.9. Строки shebang

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

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

• /usr/bin/env <ALIAS>
• /usr/bin/env -S <ALIAS>
• /usr/bin/<ALIAS>
• /usr/local/bin/<ALIAS>
• <ALIAS>

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

#! /usr/bin/python

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

В любой из перечисленных выше виртуальных команд вместо <ALIAS> можно указать псевдоним установленной среды выполнения. Иными словами, в строке shebang можно использовать любую команду, созданную в каталоге глобальных псевдонимов (который можно добавить в переменную среды PATH), даже если её нет в переменной PATH. Это позволяет использовать строки shebang, например /usr/bin/python3.12, для выбора конкретной среды выполнения.

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

Форма строки shebang /usr/bin/env также выполняет поиск нераспознанных команд в переменной среды PATH. Это соответствует поведению программы Unix env, выполняющей такой же поиск, но отдающей предпочтение запуску известных команд Python. При поиске произвольных исполняемых файлов может отображаться предупреждение; этот поиск можно отключить параметром конфигурации shebang_can_run_anything.

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

Начиная с версии 26.3 диспетчера установки Python в файл конфигурации можно добавлять пользовательские шаблоны shebang. Добавьте объект shebang_templates с одним элементом для каждого шаблона (строкой для сопоставления) и командой, которую следует использовать при совпадении с шаблоном. Для запуска одной из установленных сред выполнения в большинстве команд следует использовать py -V:<tag> (или pyw). Также допускается форма py -3.<version> и обычный py для запуска среды выполнения по умолчанию. Другие аргументы не поддерживаются.

{
    "shebang_templates": {
        "/usr/bin/python": "py",
        "/usr/bin/my_custom_python": "py -V:MyCustomPython/3"
    }
}

Если подставляемая команда не является py или pyw, она будет записана обратно в строку shebang, после чего продолжится обычная обработка. Если запуск произвольных исполняемых файлов разрешён, указание полного пути позволит перенаправить запуск с Python на любой исполняемый файл. Шаблон должен соответствовать либо всей строке (без учёта начальных и конечных пробелов), либо тексту до первого пробела в строке shebang.

4.1.10. Расширенная установка

Если установить MSIX невозможно, например на некоторых старых платформах для административного развертывания, на странице загрузок python.org доступен MSI-пакет. У этого MSI нет пользовательского интерфейса, и он может выполнять установку только для всего компьютера в расположение по умолчанию в Program Files. Он попытается изменить системную переменную среды PATH, добавив в неё путь установки, но обязательно проверьте, как это работает в вашей конфигурации.

Обратите внимание, что пакет MSI не включает среду выполнения, поэтому он не подходит для установки в автономной среде, если предварительно не создан автономный индекс установки. Информацию об обработке таких сценариев см. в разделах Автономная установка и Административная конфигурация.

Среды выполнения, установленные с помощью MSI, являются общими со средами, установленными с помощью MSIX, и устанавливаются только для текущего пользователя. Менеджер установки Python не поддерживает установку сред выполнения для всего компьютера. Чтобы имитировать установку для всего компьютера, можно запустить py install --target=<shared location> с правами администратора и добавить собственные системные изменения в PATH, реестр или меню «Пуск».

Если MSIX установлен, но команды недоступны в переменной среды PATH, их можно найти в %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km или %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0 — в зависимости от того, был ли пакет установлен с python.org или через Microsoft Store. Запуск исполняемого файла непосредственно из Program Files не рекомендуется.

Для программной установки менеджера установки Python проще всего использовать WinGet, который входит во все поддерживаемые версии Windows:

$> winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity

# Optionally run the configuration checker and accept all changes
$> py install --configure -y

Чтобы скачать менеджер установки Python и установить его на другой компьютер, следующая команда WinGet загрузит необходимые файлы из Store в каталог «Загрузки» (добавьте -d <location>, чтобы изменить расположение вывода). При этом также создаётся YAML-файл, который, по-видимому, не нужен: загруженный MSIX можно установить, запустив его или используя приведённые ниже команды.

$> winget download 9NQ7512CXL7T -e --skip-license --accept-package-agreements --accept-source-agreements

Для программной установки или удаления MSIX только с помощью PowerShell рекомендуется использовать командлеты PowerShell Add-AppxPackage и Remove-AppxPackage:

$> Add-AppxPackage C:\Downloads\python-manager-25.0.msix
...
$> Get-AppxPackage PythonSoftwareFoundation.PythonManager | Remove-AppxPackage

Последнюю версию можно скачать и установить в Windows, передав файл AppInstaller команде Add-AppxPackage. При этом используется MSIX с python.org. Этот способ рекомендуется только в случаях, когда установка через Store (в интерактивном режиме или с помощью WinGet) невозможна.

$> Add-AppxPackage -AppInstallerFile https://www.python.org/ftp/python/pymanager/pymanager.appinstaller

Для развертывания пакета MSIX для всех пользователей компьютера можно использовать и другие инструменты и API, но Python не считает такой сценарий поддерживаемым. Рекомендуем изучить командлет PowerShell Add-AppxProvisionedPackage, класс PackageManager из Windows или документацию и справочные материалы по используемому инструменту развертывания.

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

Обратите внимание: загружаемые из Store и с веб-сайта Python версии MSIX немного отличаются, поэтому их нельзя установить одновременно. По возможности рекомендуем использовать приведённые выше команды WinGet для загрузки пакета из Store, чтобы снизить риск конфликтующих установок. Лицензионных ограничений, которые запрещали бы использовать таким образом пакет из Store, для менеджера установки Python нет.

4.1.11. Административная конфигурация

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

Параметры конфигурации можно переопределить в реестре, задав значения в разделе HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager, где имя значения соответствует ключу конфигурации, а тип значения — REG_SZ. Обратите внимание: сам этот раздел можно настроить, но только изменив основной файл конфигурации, распространяемый вместе с менеджером установки Python. Однако мы рекомендуем использовать значения реестра только для установки base_config в путь к JSON-файлу с полным набором переопределений. Переопределения в реестре заменяют любые другие заданные параметры, а base_config позволяет пользователям дополнительно изменять необходимые им параметры.

Обратите внимание: большинство параметров с переменными среды поддерживают эти переменные, поскольку их значения по умолчанию содержат ссылки на них. При переопределении таких параметров переменная среды больше не будет работать, если только вы не укажете другую переменную. Например, значение по умолчанию confirm — это буквально %PYTHON_MANAGER_CONFIRM%, и переменная раскрывается при загрузке. Если переопределить значение на yes, переменная среды больше не будет использоваться. Если переопределить значение на %CONFIRM%, вместо неё будет использоваться эта переменная среды.

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

Параметры административной конфигурации

4.1.12. Установка свободнопоточных двоичных файлов

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

$> py install 3.14t
$> py install 3.14t-arm64
$> py install 3.14t-32

Установка и регистрация выполняются как обычно. Если у вас не установлены другие среды выполнения, команда python запустит эту среду. В противном случае потребуется использовать py -V:3.14t ... или, если вы добавили каталог глобальных псевдонимов в переменную среды PATH, команды python3.14t.exe.

4.1.13. Подписи индекса

Файлы индекса можно подписывать, чтобы обнаруживать подмену. Подпись — это файл каталога, расположенный по тому же URL-адресу, что и индекс, с добавленным к имени файла .cat. Файл каталога должен содержать хеш соответствующего файла индекса и быть подписан действительной подписью Authenticode. Это позволяет создавать подпись с помощью стандартных инструментов (в Windows); можно использовать любой сертификат, если операционная система клиента уже доверяет его центру сертификации (корневому ЦС).

Подписи индекса загружаются и проверяются только в том случае, если раздел source_settings локальной конфигурации содержит URL-адрес индекса и параметр requires_signature имеет значение True либо если в JSON-файле индекса параметру requires_signature задано значение True. Если этот параметр задан в локальной конфигурации, настройки индекса игнорируются даже в том случае, когда его значение — False.

Помимо требования действительной подписи, параметры required_root_subject и required_publisher_subject позволяют дополнительно ограничить принимаемые подписи на основе полей Subject сертификата. Каждый атрибут, указанный в конфигурации, должен совпадать с атрибутом сертификата (дополнительные атрибуты сертификата игнорируются). Обычно указывают CN= для общего имени, O= для подразделения организации и C= для страны издателя.

Наконец, параметр required_publisher_eku позволяет требовать наличия у сертификата издателя определённого расширенного использования ключа (EKU). Например, EKU 1.3.6.1.5.5.7.3.3 означает, что сертификат предназначен для подписывания кода, а не для аутентификации сервера или клиента. В сочетании с определённым корневым ЦС это даёт дополнительный способ проверить подлинность подписи.

Ниже приведён пример раздела source_settings из файла конфигурации. В этом случае издатель ленты однозначно определяется сочетанием корневого центра Microsoft Identity Verification и EKU, назначенного этим центром. Для этого случая подпись будет находиться по адресу https://www.python.org/ftp/python/index-windows.json.cat.

{
  "source_settings": {
    "https://www.python.org/ftp/python/index-windows.json": {
      "requires_signature": true,
      "required_root_subject": "CN=Microsoft Identity Verification Root Certificate Authority 2020",
      "required_publisher_subject": "CN=Python Software Foundation",
      "required_publisher_eku": "1.3.6.1.4.1.311.97.608394634.79987812.305991749.578777327"
    }
  }
}

Те же параметры можно указать и в файле index.json. В этом случае корневой центр и EKU не указаны, то есть подпись должна быть действительной и иметь определённое общее имя в сертификате издателя, но другие проверки не выполняются.

{
  "requires_signature": true,
  "required_publisher_subject": "CN=Python Software Foundation",
  "versions": [
    // ...
  ]
}

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

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

Если проверка подписи не пройдёт, вы получите уведомление и запрос на продолжение. Если интерактивное подтверждение недоступно (например, из-за указанного --yes), операция всегда будет прервана. Чтобы использовать в этом случае ленту с недействительной конфигурацией, необходимо предоставить файл конфигурации, отключающий проверку подписи для этой ленты.

"source_settings": {
  "https://www.example.com/feed-with-invalid-signature.json": {
    "requires_signature": false
  }
}

4.1.14. Устранение неполадок

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

Устранение неполадок

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

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

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

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

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

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

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

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

4.3.1. Свободнопоточные пакеты

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

4.9.1. PyWin32

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

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

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

4.9.2. cx_Freeze

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.11.3. Установка без интерфейса

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

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

Все остальные параметры передаются как 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.11.4. Установка без загрузки

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

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

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

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

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

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

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

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

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

4.11.6. Установка свободнопоточных двоичных файлов

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

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

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

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

Свободнопоточные двоичные файлы также доступны на nuget.org.

4.12.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.12.2. Строки shebang

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

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

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

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

#! /usr/bin/python

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

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

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

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

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

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

4.12.3. Аргументы в строках shebang

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

#! /usr/bin/python -v

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

4.12.4. Настройка

[defaults]
python=3.7

[defaults]
python=3
python3=3.7

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

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

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

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

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

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

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

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

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

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