4. Utilizando Python no Windows

Este documento pretende dar uma visão geral do comportamento específico do Windows que você deve conhecer quando fores utilizar o Python no sistema operacional Microsoft Windows.

Ao contrário da maioria dos sistemas e serviços Unix, o Windows não inclui uma instalação do Python com suporte no sistema. Em vez disso, o Python pode ser obtido de diversos distribuidores, inclusive diretamente da equipe do CPython. Cada distribuição do Python terá suas próprias vantagens e desvantagens; no entanto, a consistência com outras ferramentas que você usa geralmente é um benefício valioso. Antes de se comprometer com o processo descrito aqui, recomendamos verificar suas ferramentas existentes para ver se elas podem fornecer Python diretamente.

To obtain Python from the CPython team, use the Python install manager. This is a standalone tool that makes Python available as global commands on your Windows machine, integrates with the system, and supports updates over time. You can download the Python install manager from python.org/downloads or through the Microsoft Store app.

Once you have installed the Python install manager, the global python command can be used from any terminal to launch your current latest version of Python. This version may change over time as you add or remove different versions, and the py list command will show which is current.

Em geral, recomendamos que você crie um ambiente virtual para cada projeto e execute <env>\Scripts\Activate no seu terminal para usá-lo. Isso proporciona isolamento entre projetos, consistência ao longo do tempo e garante que comandos adicionais adicionados por pacotes também estejam disponíveis na sua sessão. Crie um ambiente virtual usando python -m venv <caminho do ambiente>.

If the python or py commands do not seem to be working, see the Troubleshooting section below. There are sometimes additional manual steps required to configure your PC.

Além de usar o gerenciador de instalação do Python, o Python também pode ser obtido como pacotes NuGet. Veja Os pacotes nuget.org abaixo para mais informações sobre esses pacotes.

As distribuições incorporáveis são pacotes mínimos do Python adequados para incorporação em aplicações maiores. Elas podem ser instaladas usando o gerenciador de instalação do Python. Consulte O pacote embutível abaixo para obter mais informações sobre esses pacotes.

4.1. Gerenciador de instalação do Python

4.1.1. Instalação

O gerenciador de instalação do Python pode ser instalado a partir da aplicação da Microsoft Store ou baixado e instalado de python.org/downloads. As duas versões são idênticas.

Para instalar pela Store, basta clicar em “Install”. Após a conclusão, abra um terminal e digite python para começar.

To install the file downloaded from python.org, either double-click and select “Install”, or run Add-AppxPackage <path to MSIX> in Windows PowerShell.

Após a instalação, os comandos python, py e pymanager devem estar disponíveis. Se você já possui instalações do Python ou modificou a variável PATH, pode ser necessário removê-las ou desfazer as modificações. Consulte Solução de problemas para obter mais ajuda sobre como corrigir comandos que não funcionam.

When you first install a runtime, you will likely be prompted to add a directory to your PATH. This is optional, if you prefer to use the py command, but is offered for those who prefer the full range of aliases (such as python3.16.exe) to be available. The directory will be %LocalAppData%\Python\bin by default, but may be customized by an administrator. Click Start and search for “Edit environment variables for your account” for the system settings page to add the path.

Cada ambiente de execução do Python que você instalar terá seu próprio diretório para scripts. Estes também precisam ser adicionados a PATH se você quiser usá-los.

O gerenciador de instalação do Python será atualizado automaticamente para novas versões. Isso não afeta nenhuma instalação de ambientes de execução do Python. Desinstalar o gerenciador de instalação do Python não desinstala nenhum ambiente de execução do Python.

If you are not able to install an MSIX in your context, for example, you are using automated deployment software that does not support it, or are targeting Windows Server 2019, see Instalação avançada below for more information.

4.1.2. Uso básico

O comando recomendado para iniciar o Python é python, que iniciará a versão solicitada pelo script em execução, um ambiente virtual ativo ou a versão padrão instalada, que será a versão estável mais recente, a menos que configurado de outra forma. Se nenhuma versão for solicitada especificamente e nenhum ambiente de execução estiver instalado, a versão mais recente será instalada automaticamente.

Para todos os cenários que envolvem múltiplas versões de ambientes de execução do antigo inicializador py.exe. Por padrão, py corresponde ao comportamento de python, mas também permite opções de linha de comando para selecionar uma versão específica, bem como subcomandos para gerenciar instalações. Estes são detalhados abaixo.

Como o comando py pode já estar sendo executado pela versão anterior, há também um comando pymanager inequívoco. Instalações com script que pretendem usar o gerenciador de instalação Python devem considerar o uso de pymanager, devido à menor chance de conflito com instalações existentes. A única diferença entre os dois comandos é que, quando executados sem argumentos, py iniciará seu interpretador padrão, enquanto pymanager exibirá ajuda (pymanager exec ... oferece comportamento equivalente a py ...).

Cada um desses comandos também possui uma versão em janela que evita a criação de uma janela de console. São eles pyw, pythonw e pywmanager. Um comando python3 também está incluído, imitando o comando python. Ele visa detectar usos acidentais do comando POSIX típico no Windows, mas não se destina a ser amplamente utilizado ou recomendado.

Para iniciar seu ambiente de execução padrão, execute python ou py com os argumentos que você deseja passar para o ambiente de execução (como arquivos de script ou o módulo a ser iniciado):

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

O ambiente de execução padrão pode ser substituído pela variável de ambiente PYTHON_MANAGER_DEFAULT ou por um arquivo de configuração. Consulte Configuração para obter informações sobre as configurações.

Para iniciar um ambiente de execução específico, o comando py aceita a opção -V:<TAG>. Esta opção deve ser especificada antes de quaisquer outras. A tag é parte ou todo o identificador do ambiente; para aqueles da equipe do CPython, parece a versão, potencialmente com a plataforma. Para compatibilidade, o V: pode ser omitido nos casos em que a tag se refere a uma versão oficial e começa com 3.

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

Ambientes de execução de outros distribuidores podem exigir a inclusão da company também. Ela deve ser separada da tag por uma barra (/ ou \) e pode ser encurtada a qualquer prefixo de sua valor completo. Especificar a empresa é opcional quando se trata de PythonCore, e especificar a tag é opcional (mas não a barra) quando se deseja a versão mais recente de uma empresa específica.

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

Se nenhuma versão for especificada, mas um arquivo de script for passado, o script será inspecionado em busca de uma linha de shebang. Este é um formato especial para a primeira linha de um arquivo que permite a substituição do comando. Consulte Linhas shebang para obter mais informações. Quando não houver uma linha shebang ou o problema não puder ser resolvido, o script será iniciado com o ambiente de execução padrão.

Se você estiver executando em um ambiente virtual ativo, não tiver solicitado uma versão específica e não houver uma linha shebang, o ambiente de execução padrão será o ambiente virtual em questão. Nesse cenário, o comando python provavelmente já foi substituído e nenhuma dessas verificações ocorreu. No entanto, esse comportamento garante que o comando py possa ser usado de forma intercambiável.

Quando nenhum ambiente de execução estiver instalado, qualquer comando de inicialização tentará instalar a versão solicitada e iniciá-la. Entretanto, após alguma versão ser instalada, apenas os comandos py exec ... e pymanager exec ... serão instalados se a versão solicitada estiver ausente. Outras formas de comandos exibirão um erro e orientarão você a usar py install primeiro.

4.1.3. Comando help

O comando py help exibirá a lista completa de comandos suportados, juntamente com suas opções. Qualquer comando pode receber a opção -? para exibir sua ajuda, ou seu nome pode ser passado para py help.

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

Todos os comandos oferecem suporte a algumas opções comuns, que serão exibidas por py help. Essas opções devem ser especificadas após qualquer subcomando. Especificar -v ou --verbose aumentará a quantidade de saída exibida, e -vv aumentará ainda mais para fins de depuração. Passar -q ou --quiet reduzirá a saída, e -qq a reduzirá ainda mais.

A opção --config=<PATH> permite especificar um arquivo de configuração para substituir várias configurações simultaneamente. Consulte Configuração abaixo para obter mais informações sobre esses arquivos.

4.1.4. Listando ambientes de execução

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

A lista de ambientes de execução instalados pode ser visualizada usando py list. Um filtro pode ser adicionado na forma de uma ou mais tags (com ou sem especificador de empresa), e cada uma pode incluir um prefixo <, <=, >= ou > para restringir a um intervalo.

A range of formats are supported, and can be passed as the --format=<FMT> or -f <FMT> option. Formats include table (a user-friendly table view), csv (comma-separated table), json (a single JSON blob), jsonl (one JSON blob per result), exe (just the executable path), prefix (just the prefix path).

A opção --one ou -1 exibe apenas um único resultado. Se o ambiente de execução padrão estiver incluído, será ele. Caso contrário, o “melhor” resultado será exibido (“melhor” é definido de forma deliberadamente vaga, mas geralmente será a versão mais recente). O resultado exibido por py list --one <TAG> corresponderá ao ambiente de execução que seria iniciado por py -V:<TAG>.

A opção --only-managed exclui resultados que não foram instalados pelo gerenciador de instalação do Python. Isso é útil para determinar quais ambientes de execução podem ser atualizados ou desinstalados por meio do comando py.

A opção --online é uma abreviação de --source=<URL> com a fonte padrão. Passar qualquer uma dessas opções pesquisará no índice online os ambientes de execução que podem ser instalados. O resultado exibido por py list --online --one <TAG> corresponderá ao ambiente de execução que seria instalado por py install <TAG>.

$> py list --online 3.16

For compatibility with the old launcher, the --list, --list-paths, -0 and -0p commands (for example, py -0p) are retained. They do not allow additional options, and will produce legacy-formatted output.

4.1.5. Instalando ambientes de execução

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

Novas versões de ambientes de execução podem ser adicionadas usando py install. Uma ou mais tags podem ser especificadas, e a tag especial default pode ser usada para selecionar o padrão. Intervalos não são suportados para instalação.

CPython publishes multiple runtime variants. For most users, PythonCore is recommended and provides the standard CPython runtime. Tags without any prefix are treated as PythonCore\<TAG>.

PythonTest includes the standard runtime together with the test suite and debugging symbols. It is intended for contributors or users who need these additional files for testing or debugging Python.

PythonEmbed provides a minimal embeddable distribution for applications that bundle Python rather than for interactive use. It would normally be used with the --target option described below.

To see the available runtime variants, run:

py list --online

To install a specific variant, include it in the tag passed to py install:

py install PythonTest\3.16

A opção --source=<URL> permite substituir o índice online usado para obter ambientes de execução. Isso pode ser usado com um índice offline, como mostrado em Instalações offline.

Passar --force ignorará quaisquer arquivos em cache e removerá qualquer instalação existente para substituí-la pela especificada.

Passing --update will replace existing installs if the new version is newer. Otherwise, they will be left. If no tags are provided with --update, all installs managed by the Python install manager will be updated if newer versions are available. Updates will remove any modifications made to the install, including globally installed packages, but will leave site-packages and Scripts directories as is. Virtual environments are also unaffected.

Passar --dry-run gerará saída e logs, mas não modificará nenhuma instalação.

Passing --refresh will update all registrations for installed runtimes. This will recreate Start menu shortcuts, registry keys, and global aliases (such as python3.16.exe or for any installed scripts). These are automatically refreshed on installation of any runtime, but may need to be manually refreshed after installing packages.

In addition to the above options, the --target option will extract the runtime to the specified directory instead of doing a normal install. This is useful for embedding runtimes into larger applications. Unlike a normal install, py will not be aware of the extracted runtime, and no Start menu or other shortcuts will be created. To launch the runtime, directly execute the main executable (typically python.exe) in the target directory.

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

The py exec command will install the requested runtime if it is not already present. This is controlled by the automatic_install configuration (PYTHON_MANAGER_AUTOMATIC_INSTALL), and is enabled by default. If no runtimes are available at all, all launch commands will do an automatic install if the configuration setting allows. This is to ensure a good experience for new users, but should not generally be relied on rather than using the py exec command or explicit install commands.

4.1.6. Instalações offline

Para executar instalações offline do Python, você precisará primeiro criar um índice offline em uma máquina que tenha acesso à rede.

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

A opção --download=<PATH> baixará os pacotes para as tags listadas e criará um diretório contendo-os e um arquivo index.json adequado para instalação posterior. Todo esse diretório pode ser movido para a máquina offline e usado para instalar um ou mais dos ambientes de execução incluídos:

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

O gerenciador de instalação do Python pode ser instalado baixando seu instalador e movendo-o para outra máquina antes da instalação.

Como alternativa, os arquivos ZIP em um diretório de índice offline podem ser simplesmente transferidos para outra máquina e extraídos. Isso não registrará a instalação de forma alguma e, portanto, ela deve ser iniciada referenciando diretamente os executáveis no diretório extraído, mas às vezes é uma abordagem preferível em casos em que a instalação do gerenciador de instalação do Python não é possível ou conveniente.

Dessa forma, os ambientes de execução do Python podem ser instalados e gerenciados em uma máquina sem acesso à internet.

4.1.7. Desinstalando ambientes de execução

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

Ambientes de execução pode ser removidos com o uso do comando py uninstall. Uma ou mais tags devem ser especificadas. Não há suporte para intervalos aqui.

A opção --yes ignora o prompt de confirmação antes da desinstalação.

Em vez de passar as tags individualmente, a opção --purge pode ser especificada. Isso removerá todos os ambientes de execução gerenciados pelo gerenciador de instalação do Python, incluindo a limpeza do menu Iniciar, do registro e de quaisquer caches de download. Ambientes de execução que não foram instalados pelo gerenciador de instalação do Python não serão afetados, nem os arquivos de configuração criados manualmente.

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

O gerenciador de instalação do Python pode ser desinstalado por meio da página de configurações “Aplicativos instalados” do Windows. Isso não remove nenhum ambiente de execução, e eles ainda poderão ser usados, embora o python global e o comando py sejam removidos. A reinstalação do gerenciador de instalação do Python permitirá que você gerencie esses ambientes de execução novamente. Para limpar completamente todos os ambientes de execução do Python, execute o --purge antes de desinstalar o gerenciador de instalação do Python.

4.1.8. Configuração

O gerenciador de instalação do Python é configurado com uma hierarquia de arquivos de configuração, variáveis de ambiente, opções de linha de comando e configurações de registro. Em geral, os arquivos de configuração têm a capacidade de configurar tudo, incluindo a localização de outros arquivos de configuração, enquanto as configurações de registro são exclusivas do administrador e substituem os arquivos de configuração. As opções de linha de comando substituem todas as outras configurações, mas nem todas as opções estão disponíveis.

Esta seção descreverá os padrões, mas esteja ciente de que instalações modificadas ou substituídas podem resolver as configurações de maneira diferente.

A global configuration file may be configured by an administrator and would be read first. The user configuration file is stored at %AppData%\Python\pymanager.json (note that this location is under Roaming, not Local) and is read next, overwriting any settings from earlier files. An additional configuration file may be specified as the PYTHON_MANAGER_CONFIG environment variable or the --config command line option (but not both). These locations may be modified by administrative customization options listed later.

As configurações a seguir são aquelas que provavelmente serão modificadas em uso normal. As seções posteriores listam aquelas destinadas à personalização administrativa.

Opções de configuração padrão

Chave de configuração	Variável de ambiente	Descrição
default_tag	PYTHON_MANAGER_DEFAULT	A versão padrão preferida para iniciar ou instalar. Por padrão, esta é interpretada como a versão mais recente, não pré-lançada, da equipe do CPython.
default_platform	PYTHON_MANAGER_DEFAULT_PLATFORM	The preferred default platform to launch or install. This is treated as a suffix to the specified tag, such that py -V:3.16 would prefer an install for 3.16-64 if it exists (and default_platform is -64), but will use 3.16 if no tagged install exists.
logs_dir	PYTHON_MANAGER_LOGS	O local onde os arquivos de log são gravados. Por padrão, %TEMP%.
automatic_install	PYTHON_MANAGER_AUTOMATIC_INSTALL	True to allow automatic installs when using py exec to launch (or py when no runtimes are installed yet). Other commands will not automatically install, regardless of this setting. By default, true.
include_unmanaged	PYTHON_MANAGER_INCLUDE_UNMANAGED	Verdadeiro para permitir a listagem e a execução de ambientes que não foram instalados pelo gerenciador de instalação do Python, ou falso para excluí-los. Por padrão, verdadeiro.
shebang_can_run_anything	PYTHON_MANAGER_SHEBANG_CAN_RUN_ANYTHING	Verdadeiro para permitir que shebangs em arquivos .py iniciem aplicação que não sejam ambientes de execução do Python, ou falso para evitar isso. Por padrão, verdadeiro.
shebang_templates	(nenhuma)	Mapping from shebang line template to alternative command, such as py -V:<tag> or a substitute string. See Linhas shebang for more details.
log_level	PYMANAGER_VERBOSE, PYMANAGER_DEBUG	Define o nível padrão de saída (0-50). O padrão é 20. Valores mais baixos produzem mais saída. As variáveis de ambiente são booleanas e podem produzir saída adicional durante a inicialização, que é posteriormente suprimida por outra configuração.
confirm	PYTHON_MANAGER_CONFIRM	True para confirmar certas ações antes de executá-las (como desinstalar) ou False para ignorar a confirmação. Por padrão, True.
install.source	PYTHON_MANAGER_SOURCE_URL	Substitui o feed de índice para obter novas instalações.
install.enable_entrypoints	(nenhuma)	True to generate global commands for installed packages (such as pip.exe). These are defined by the packages themselves. If set to false, only the Python interpreter has global commands created. By default, true. You should run py install --refresh after changing this setting.
list.format	PYTHON_MANAGER_LIST_FORMAT	Especifica o formato padrão usado pelo comando py list. Por padrão, table.
install_dir	(nenhuma)	Especifica o diretório raiz onde os ambientes de execução serão instalados. Se você alterar essa configuração, os ambientes de execução instalados anteriormente não poderão ser usados, a menos que você os mova para o novo local.
global_dir	(nenhuma)	Specify the directory where global commands (such as python3.16.exe and pip.exe) are stored. This directory should be added to your PATH to make the commands available from your terminal.
download_dir	(nenhuma)	Especifica o diretório onde os arquivos baixados serão armazenados. Este diretório é um cache temporário e pode ser limpo periodicamente.

Nomes pontilhados devem ser aninhados dentro de objetos JSON, por exemplo, list.format seria especificado como {"list": {"format": "table"}}.

4.1.9. Linhas shebang

If the first line of a script file starts with #!, it is known as a “shebang” line. Linux and other Unix-like operating systems have native support for such lines and they are commonly used on such systems to indicate how a script should be executed. The python and py commands allow the same facilities to be used with Python scripts on Windows.

Para permitir que as linhas shebang em scripts Python sejam portáveis entre Unix e Windows, vários comandos “virtuais” são suportados para especificar qual interpretador usar. Os comandos virtuais suportados são:

• /usr/bin/env <ALIAS>

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

• /usr/bin/<ALIAS>

• /usr/local/bin/<ALIAS>

• <ALIAS>

Por exemplo, se a primeira linha do seu script começa com

#! /usr/bin/python

O Python padrão ou um ambiente virtual ativo será localizado e utilizado. Como muitos scripts Python escritos para funcionar no Unix já terão essa linha, você deve perceber que esses scripts podem ser usados pelo inicializador sem modificação. Se você está escrevendo um novo script no Windows que você espera que seja útil no Unix, você deve usar uma dessas linhas shebang começando com /usr.

Qualquer um dos comandos virtuais acima pode ter o <ALIAS> substituído por um apelido de um ambiente de execução instalado. Ou seja, qualquer comando gerado no diretório global de apelidos (que você pode ter adicionado à sua variável de ambiente PATH) pode ser usado em uma shebang, mesmo que não esteja no seu PATH. Isso permite o uso de shebangs como /usr/bin/python3.12 para selecionar um determinado ambiente de execução.

Se nenhum ambiente de execução estiver instalado ou se a instalação automática estiver ativada, o ambiente de execução solicitado será instalado, se necessário. Consulte Configuração para obter informações sobre as definições de configuração.

A forma /usr/bin/env da linha shebang também pesquisará a variável de ambiente PATH em busca de comandos não reconhecidos. Isso corresponde ao comportamento do programa env do Unix, que realiza a mesma busca, mas prefere executar comandos Python conhecidos. Um aviso pode ser exibido ao pesquisar executáveis arbitrários, e essa busca pode ser desabilitada pela opção de configuração shebang_can_run_anything.

Shebang lines that do not match any of the patterns are treated as Windows executable paths that are absolute or relative to the directory containing the script file. This is a convenience for Windows-only scripts, such as those generated by an installer, since the behavior is not compatible with Unix-style shells. These paths may be quoted, and may include multiple arguments, after which the path to the script and any additional arguments will be appended. This functionality may be disabled by the shebang_can_run_anything configuration option.

Since version 26.3 of the Python install manager, custom shebang templates may be added to your configuration file. Add the shebang_templates object with one member for each template (the string to match) and the command to use when the template is matched. Most commands should be py -V:<tag> (or pyw) to launch one of your installed runtimes. The py -3.<version> form is also allowed, as is a plain py to launch the default. No other arguments are supported.

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

If the substitute command is not py or pyw, it will be written back into the shebang and regular handling continues. If launching arbitrary executables is permitted, then providing a full path will allow you to redirect from Python to any executable. The template should match either the entire line (ignoring leading and trailing whitespace), or up to the first space in the shebang line.

Nota

O comportamento dos shebangs no gerenciador de instalação do Python é sutilmente diferente do antigo inicializador py.exe, e as opções de configuração antigas não se aplicam mais. Se você depende especificamente do comportamento ou configuração antigos, recomendamos instalar o inicializador legado. O comando py do inicializador legado vai substituir o do PyManager por padrão, e você precisará usar os comandos pymanager para instalar e desinstalar.

4.1.10. Instalação avançada

Para situações em que um MSIX não pode ser instalado, como em algumas plataformas de distribuição administrativa mais antigas, há um MSI disponível na página de downloads do python.org. Este MSI não possui interface de usuário e só pode executar instalações por máquina em seu local padrão em Arquivos de Programas. Ele tentará modificar a variável de ambiente do sistema PATH para incluir este local de instalação, mas certifique-se de validar isso em sua configuração.

Nota

O Windows Server 2019 é a única versão do Windows compatível com o CPython que não oferece suporte a MSIX. Para o Windows Server 2019, você deve usar o MSI.

Esteja ciente que o pacote MSI não inclui nenhum ambiente de execução e, portanto, não é adequado para instalações em ambientes off-line sem criar também um indíce para instalação off-line. Consulte Instalações offline e Configuração administrativa para obter informações sobre como lidar com esses cenários.

Ambientes de execução instalados pelo MSI são compartilhados com os instalados pelo MSIX e são todos apenas por usuário. O gerenciador de instalação do Python não permite a instalação de ambientes de execução por máquina. Para emular uma instalação por máquina, você pode usar o py install --target=<shared location> como administrador e adicionar suas próprias modificações em todo o sistema ao PATH, ao registro ou ao menu Iniciar.

Quando o MSIX é instalado, mas os comandos não estão disponíveis na variável de ambiente PATH, eles podem ser encontrados em %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_3847v3x7pw1km ou %LocalAppData%\Microsoft\WindowsApps\PythonSoftwareFoundation.PythonManager_qbz5n2kfra8p0, dependendo se foi instalado a partir do python.org ou da Windows Store. Não é recomendável tentar executar o executável diretamente dos Arquivos de Programas.

Para instalar programaticamente o gerenciador de instalação do Python, é mais fácil usar o WinGet, que está incluído em todas as versões suportadas do Windows:

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

# Opcionalmente execute o verificador de configuraçao e aceite todas as alterações
$> py install --configure -y

Para baixar o gerenciador de instalação do Python e instalá-lo em outra máquina, o seguinte comando WinGet baixará os arquivos necessários da Loja para o seu diretório de Downloads (adicione -d <local> para personalizar o local de saída). Isso também gera um arquivo YAML que parece desnecessário, pois o MSIX baixado pode ser instalado iniciando ou usando os comandos abaixo.

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

Para instalar ou desinstalar programaticamente um MSIX usando apenas o PowerShell, os cmdlets Add-AppxPackage e Remove-AppxPackage do PowerShell são recomendados:

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

A versão mais recente pode ser baixada e instalada pelo Windows passando o arquivo AppInstaller para o comando Add-AppxPackage. A instalação é feita usando o MSIX em python.org e é recomendada apenas para casos em que a instalação pela Loja (interativamente ou usando o WinGet) não é possível.

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

Outras ferramentas e APIs também podem ser usadas para provisionar um pacote MSIX para todos os usuários em uma máquina, mas o Python não considera esse cenário compatível. Sugerimos consultar o cmdlet Add-AppxProvisionedPackage do PowerShell, a classe nativa PackageManager do Windows ou a documentação e o suporte da sua ferramenta de implantação.

Regardless of the install method, users will still need to install their own copies of Python itself, as there is no way to trigger those installs without being a logged-in user. When using the MSIX, the latest version of Python will be available for all users to install without network access.

Observe que o MSIX disponível para download na Loja e no site do Python são ligeiramente diferentes e não podem ser instalados ao mesmo tempo. Sempre que possível, sugerimos usar os comandos WinGet acima para baixar o pacote da Loja, a fim de reduzir o risco de instalação conflitante. Não há restrições de licenciamento para o gerenciador de instalação do Python que impeçam o uso do pacote da Loja dessa forma.

4.1.11. Configuração administrativa

Há diversas opções que podem ser úteis para administradores substituírem a configuração do gerenciador de instalação do Python. Elas podem ser usadas para fornecer cache local, desabilitar certos tipos de atalhos e substituir conteúdo agrupado. Todas as opções de configuração acima podem ser definidas, assim como as abaixo.

As opções de configuração podem ser substituídas no registro definindo valores em HKEY_LOCAL_MACHINE\Software\Policies\Python\PyManager, onde o nome do valor corresponde à chave de configuração e o tipo de valor é REG_SZ. Observe que essa chave pode ser personalizada, mas somente modificando o arquivo de configuração principal distribuído com o gerenciador de instalação do Python. Recomendamos, no entanto, que os valores do registro sejam usados apenas para definir base_config como um arquivo JSON contendo o conjunto completo de substituições. As substituições de chave do registro substituirão qualquer outra configuração configurada, enquanto base_config permite que os usuários modifiquem ainda mais as configurações necessárias.

Observe que a maioria das configurações com variáveis de ambiente oferece suporte a essas variáveis porque a configuração padrão especifica a variável. Se você as substituir, a variável de ambiente não funcionará mais, a menos que você a substitua por outra. Por exemplo, o valor padrão de confirm é literalmente %PYTHON_MANAGER_CONFIRM%, o que resolverá a variável no momento do carregamento. Se você substituir o valor para yes, a variável de ambiente não será mais usada. Se você substituir o valor para %CONFIRM%, essa variável de ambiente será usada.

As definições de configuração que são caminhos são interpretadas como relativas ao diretório que contém o arquivo de configuração que as especificou.

Opções de configuração administrativa

Chave de configuração	Descrição
base_config	O arquivo de configuração de maior prioridade para leitura. Observe que somente o arquivo de configuração embutido e o registro podem modificar essa configuração.
user_config	O segundo arquivo de configuração a ser lido.
additional_config	O terceiro arquivo de configuração a ser lido.
registry_override_key	Local do registro para verificar se há substituições. Observe que somente o arquivo de configuração embutido pode modificar esta configuração.
bundled_dir	Diretório somente leitura contendo arquivos armazenados em cache localmente.
install.fallback_source	Caminho ou URL para um índice a ser consultado quando o índice principal não puder ser acessado.
install.enable_shortcut_kinds	Comma-separated list of shortcut kinds to allow (for example, "pep514,start"). Enabled shortcuts may still be disabled by disable_shortcut_kinds.
install.disable_shortcut_kinds	Comma-separated list of shortcut kinds to exclude (for example, "pep514,start"). Disabled shortcuts are not reactivated by enable_shortcut_kinds.
install.hard_link_entrypoints	True to use hard links for global shortcuts to save disk space. If false, each shortcut executable is copied instead. After changing this setting, you must run py install --refresh --force to update existing commands. By default, true. Disabling this may be necessary for troubleshooting or systems that have issues with file links.
pep514_root	Local do registro para leitura e gravação de entradas da PEP 514. Por padrão, HKEY_CURRENT_USER\Software\Python.
start_folder	Pasta do menu Iniciar para gravar atalhos. Por padrão, Python. Este caminho é relativo à pasta Programas do usuário.
virtual_env	Caminho para o ambiente virtual ativo. Por padrão, é %VIRTUAL_ENV%, mas pode ser definido como vazio para desabilitar a detecção de venv.
shebang_can_run_anything_silently	Verdadeiro para suprimir avisos visíveis quando um shebang executa uma aplicação que não seja um ambiente de execução Python.
source_settings	A mapping from source URL to settings specific to that index. When multiple configuration files include this section, URL settings are added or overwritten, but individual settings are not merged. These settings are currently only for index signatures.

4.1.12. Instalando binários com threads livres

Adicionado na versão 3.13.

Distribuições pré-construídas da construção com threads livres estão disponíveis instalando tags com o sufixo t.

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

This will install and register as normal. If you have no other runtimes installed, then python will launch this one. Otherwise, you will need to use py -V:3.16t or, if you have added the global aliases directory to your PATH environment variable, the python3.16t.exe commands.

4.1.13. Index signatures

Adicionado na versão 26.2.

Index files may be signed to detect tampering. A signature is a catalog file at the same URL as the index with .cat added to the filename. The catalog file should contain the hash of its matching index file, and should be signed with a valid Authenticode signature. This allows standard tooling (on Windows) to generate a signature, and any certificate may be used as long as the client operating system already trusts its certification authority (root CA).

Index signatures are only downloaded and checked when the local configuration’s source_settings section includes the index URL and requires_signature is true, or the index JSON contains requires_signature set to true. When the setting exists in local configuration, even when false, settings in the index are ignored.

As well as requiring a valid signature, the required_root_subject and required_publisher_subject settings can further restrict acceptable signatures based on the certificate Subject fields. Any attribute specified in the configuration must match the attribute in the certificate (additional attributes in the certificate are ignored). Typical attributes are CN= for the common name, O= for the organization, and C= for the publisher’s country.

Finally, the required_publisher_eku setting allows requiring that a specific Enhanced Key Usage (EKU) has been assigned to the publisher certificate. For example, the EKU 1.3.6.1.5.5.7.3.3 indicates that the certificate was intended for code signing (as opposed to server or client authentication). In combination with a specific root CA, this provides another mechanism to verify a legitimate signature.

This is an example source_settings section from a configuration file. In this case, the publisher of the feed is uniquely identified by the combination of the Microsoft Identity Verification root and the EKU assigned by that root. The signature for this case would be found at 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"
    }
  }
}

The same settings could be specified in the index.json file instead. In this case, the root and EKU are omitted, meaning that the signature must be valid and have a specific common name in the publisher’s certificate, but no other checks are used.

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

When settings from inside a feed are used, the user is notified and the settings are shown in the log file or verbose output. It is recommended to copy these settings into a local configuration file for feeds that will be used frequently, so that unauthorised modifications to the feed cannot disable verification.

It is not possible to override the location of the signature file in the feed or through a configuration file. Administrators can provide their own source_settings in a mandatory configuration file (see Configuração administrativa).

If signature validation fails, you will be notified and prompted to continue. When interactive confirmation is not allowed (for example, because --yes was specified), it will always abort. To use a feed with invalid configuration in this scenario, you must provide a configuration file that disables signature checking for that feed.

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

4.1.14. Proxy settings

Adicionado na versão 26.4.

By default, the Python install manager will use your system-wide proxy settings, including automatic authentication. For most users, this behaves the same as your browser and other applications.

To override the settings, use the NO_PROXY, HTTP_PROXY and HTTPS_PROXY environment variables. These should be set in the terminal session before using the Python install manager. Other applications may also use the variables, so use caution before setting them globally for your entire machine.

Setting NO_PROXY to any non-empty value will disable the use of any proxy. Use this to bypass your system’s default proxy setting and attempt to access the index server directly.

Setting HTTPS_PROXY to a string like example.com:8080 will connect to that proxy server for all HTTPS connections. For the default index, all connections will be using HTTPS, and so this is the usual setting to override.

The HTTP_PROXY variable may be needed if you are using a private index server that does not use encrypted connections, but does require the default proxy server to be overridden. It follows the same format as HTTPS_PROXY.

Credentials may be embedded in either setting, however, when HTTPS_PROXY has credentials embedded they will be used in preference to other credentials. Only one set of credentials will be used for both types of proxy.

4.1.15. Solução de problemas

If your Python install manager does not seem to be working correctly, work through these tests and fixes to see if it helps. If not, report an issue at our bug tracker, including any relevant log files (written to your %TEMP% directory by default).

Solução de problemas

Sintoma	Coisas pra tentar
python retorna um erro “comando não encontrado” ou abre o aplicativo Store quando eu o digito no meu terminal.	Você instalou o gerenciador de instalação do Python?
	Clique em Iniciar, abra “Gerenciar aliases de execução de aplicativo” e verifique se os apelidos (aliases) para “Python (default)” estão ativados. Se já estiverem, tente desativá-los e ativá-los novamente para atualizar o comando. Os comandos “Python (windowed)” e “Python install manager” também podem precisar ser atualizados.
	Verifique se os comandos py e pymanager funcionam.
	Ensure your PATH variable contains the entry for %UserProfile%\AppData\Local\Microsoft\WindowsApps. The operating system includes this entry once by default, after other user paths. If removed, shortcuts will not be found.
py me dá um erro “comando não encontrado” quando eu digito no meu terminal.	Você instalou o gerenciador de instalação do Python?
	Clique em Iniciar, abra “Gerenciar aliases de execução de aplicativo” e verifique se os apelidos (aliases) para “Python (default)” estão ativados. Se já estiverem, tente desativá-los e ativá-los novamente para atualizar o comando. Os comandos “Python (windowed)” e “Python install manager” também podem precisar ser atualizados.
	Ensure your PATH variable contains the entry for %UserProfile%\AppData\Local\Microsoft\WindowsApps. The operating system includes this entry once by default, after other user paths. If removed, shortcuts will not be found.
py me dá um erro “não é possível abrir o arquivo” quando digito comandos no meu terminal.	Isso geralmente significa que você tem o inicializador legado instalado e ele tem prioridade sobre o gerenciador de instalação do Python. Para remover, clique em Iniciar, abra “Aplicativos instalados”, procure por “Python launcher” e desinstale-o.
python não inicia o mesmo ambiente de execução que py	Clique em Iniciar, abra “Aplicativos instalados”, procure por qualquer ambiente de execução do Python existente e remova-o ou modifique e desative as opções de PATH.
	Clique em Iniciar, abra “Gerenciar aliases de execução de aplicativo” e verifique se o apelido python.exe está definido como “Python (default)”
python e py não iniciam o ambiente de execução que eu esperava	Verifique a variável de ambiente PYTHON_MANAGER_DEFAULT ou a configuração default_tag. O comando py list mostrará o padrão com base nessas configurações.
	As instalações gerenciadas pelo gerenciador de instalação do Python serão escolhidas antes das instalações não gerenciadas. Use py install para instalar o ambiente de execução que você espera ou configure sua tag padrão.
	Prerelease and experimental installs that are not managed by the Python install manager may be chosen ahead of stable releases. Configure your default tag or uninstall the prerelease runtime and reinstall it using py install.
pythonw ou pyw não iniciam o mesmo ambiente de execução que python ou py	Clique em Iniciar, abra “Gerenciar aliases de execução de aplicativo” e verifique se seus apelidos pythonw.exe e pyw.exe são consistentes com os outros.
pip me dá um erro “comando não encontrado” quando eu digito no meu terminal.	Você ativou um ambiente virtual? Execute o script .venv\Scripts\activate no seu terminal para ativá-lo.
	The package may be available but missing the generated executable. We recommend using the python -m pip command instead. Running py install --refresh and ensuring that the global shortcuts directory is on PATH (it will be shown in the command output if it is not) should make commands such as pip (and other installed packages) available.
I installed a package with pip but its command is not found.	Você ativou um ambiente virtual? Execute o script .venv\Scripts\activate no seu terminal para ativá-lo.
	New packages do not automatically have global shortcuts created by the Python install manager. Similarly, uninstalled packages do not have their shortcuts removed. Run py install --refresh to update the global shortcuts for newly installed packages.
Digitar script-name.py no terminal abre em uma nova janela.	Esta é uma limitação conhecida do sistema operacional. Você pode especificar py antes do nome do script, criar um arquivo em lote contendo @py "%~dpn0.py" %* com o mesmo nome do script, ou instalar o inicializador legado e selecioná-lo como associação para scripts.
Arrastar e soltar arquivos em um script não funciona.	Essa é uma limitação conhecida do sistema operacional. Ela é suportada pelo inicializador legado ou pelo gerenciador de instalação do Python quando instalado a partir do MSI.
I have installed the Python install manager multiple times.	It is possible to install from the Store or WinGet, from the MSIX on the Python website, and from the MSI, all at once. They are all compatible and will share configuration and runtimes.
	See the earlier Instalação avançada section for ways to uninstall the install manager other than the typical Installed Apps (Add and Remove Programs) settings page.
My old py.ini settings no longer work.	The new Python install manager no longer supports this configuration file or its settings, and so it will be ignored. See Configuração for information about configuration settings.

4.2. O pacote embutível

Adicionado na versão 3.5.

A distribuição embutida é um arquivo ZIP contendo um ambiente Python mínimo. Ela foi criada para atuar como parte de outra aplicação, ao invés de ser diretamente acessada por usuários finais.

Para instalar uma distribuição incorporada, recomendamos usar o comando py install com a opção --target:

$> py install 3.16-embed --target=<directory>

When extracted, the embedded distribution is (almost) fully isolated from the user’s system, including environment variables, system registry settings, and installed packages. The standard library is included as pre-compiled and optimized .pyc files in a ZIP, and python3.dll, python316.dll, python.exe and pythonw.exe are all provided. Tcl/Tk (including all dependents, such as IDLE), pip and the Python documentation are not included.

Um arquivo ._pth padrão está incluído, o qual restringe ainda mais os caminhos de pesquisa padrão (conforme descrito abaixo em Encontrando módulos). Este arquivo destina-se a ser modificado por desenvolvedores que o incorporam, conforme necessário.

Pacotes de terceiros devem ser instalados pelo instalador da aplicação juntamente com a distribuição embutida. Usar o pip para gerenciar as dependências como em uma instalação regular do Python não é suportado nessa distribuição, apesar de que com algum cuidado pode ser possível incluir e usar o pip para atualizações automáticas. Em geral, pacotes de terceiros devem ser tratados como parte da aplicação (“vendoring”) para que o desenvolvedor consiga garantir compatibilidade com versões mais recentes antes de fornecer atualizações para os usuários.

Os dois casos de uso recomendados para essa distribuição são descritos abaixo.

4.2.1. Aplicação Python

Uma aplicação escrita em Python não requer necessariamente que os usuários estejam cientes deste fato. A distribuição embutida pode ser usada neste caso para incluir uma versão privada do pacote de instalação do Python. Dependendo de quão transparente deve ser (ou pelo contrário, quão profissional deve parecer), existem duas opções.

Usar um executável especializado como inicializador requer um pouco de código, mas fornece a experiência mais transparente para os usuários. Com um inicializador personalizado, não existem indicações óbvias que o programa está rodando em Python: ícones podem ser personalizados, informações da empresa e versão podem ser especificadas, e associações de arquivo se comportam de forma apropriada. Na maioria dos casos, um inicializador personalizado deve simplesmente ser capaz de chamar Py_Main com uma linha de comando predefinida (hard-coded).

A abordagem mais simples é fornecer um arquivo batch ou um atalho gerado que chama diretamente o python.exe ou pythonw.exe com os argumentos de linha de comando necessários. Neste caso, a aplicação irá aparecer como Python e não seu nome real, e os usuários podem ter problemas em distinguir ela de outros processos ou associações de arquivo em Python.

Com a abordagem anterior, pacotes devem ser instalados como diretórios juntamente do executável do Python para garantir que estarão disponíveis no caminho do ambiente. Com o instalador especializado, pacotes podem ser armazenados em outras localidades já que há uma oportunidade de especificar o caminho de busca antes de executar a aplicação.

4.2.2. Incorporando Python

Aplicações escritas em código nativo frequentemente precisam de alguma forma de linguagem de script, e a distribuição embutida do Python pode ser usada para esse propósito. Em geral, a maior parte da aplicação é em código nativo, e uma parte irá ou invocar python.exe ou usar diretamente python3.dll. Para ambos os casos, extrair a distribuição embutida em um subdiretório da instalação da aplicação é suficiente para providenciar um interpretador Python carregável.

As with the application use, packages can be installed to any location as there is an opportunity to specify search paths before initializing the interpreter. Otherwise, there are no fundamental differences between using the embedded distribution and a regular installation.

4.3. Os pacotes nuget.org

Adicionado na versão 3.5.2.

O pacote nuget.org é um ambiente Python de tamanho reduzido criado para uso em integração contínua e construção de sistemas que não precisam de uma instalação de Python por todo o sistema da máquina. Enquanto nuget é o “gerenciador de pacotes para .NET”, ele também funciona perfeitamente bem para pacotes contendo ferramentas em tempo de construção.

Visite nuget.org para informações mais atualizadas sobre utilização do nuget. A seguir está um sumário que é suficiente para desenvolvedores Python.

The nuget.exe command line tool may be downloaded directly from https://dist.nuget.org/win-x86-commandline/latest/nuget.exe, for example, using curl or PowerShell. With the tool, the latest version of Python for 64-bit or 32-bit machines is installed using:

nuget.exe install python -ExcludeVersion -OutputDirectory .
nuget.exe install pythonx86 -ExcludeVersion -OutputDirectory .

Para selecionar uma versão específica, adicione -Version 3.x.y. O diretório de saída pode ser mudado de ., e o pacote será instalado em um subdiretório. Por padrão, o subdiretório é nomeado igual ao pacote, e sem a opção -ExcludeVersion esse nome irá incluir a versão específica instalada. Dentro do subdiretório está um diretório tools que contém a instalação do Python:

# Sem -ExcludeVersion
> .\python.3.5.2\tools\python.exe -V
Python 3.5.2

# Com -ExcludeVersion
> .\python\tools\python.exe -V
Python 3.5.2

Em geral, pacotes nuget não são atualizáveis, e novas versões devem ser instaladas lado-a-lado e referenciadas usando o caminho completo. Alternativamente, delete o diretório do pacote manualmente e instale novamente. Muitos sistemas CI irão fazer isso automaticamente se eles não preservam arquivos entre construções de projetos.

Alongside the tools directory is a build\native directory. This contains an MSBuild properties file python.props that can be used in a C++ project to reference the Python install. Including the settings will automatically use the headers and import libraries in your build.

The package information pages on nuget.org are www.nuget.org/packages/python for the 64-bit version, www.nuget.org/packages/pythonx86 for the 32-bit version, and www.nuget.org/packages/pythonarm64 for the ARM64 version.

Resolve error Unable to find package 'python' from a misconfigured nuget.config using:

nuget.exe sources add -Name "nuget.org" -source "https://api.nuget.org/v3/index.json"

4.3.1. Pacotes com threads livres

Adicionado na versão 3.13.

Packages containing free-threaded binaries are named python-freethreaded for the 64-bit version, pythonx86-freethreaded for the 32-bit version, and pythonarm64-freethreaded for the ARM64 version. These packages contain both the python3.16t.exe and python.exe entry points, both of which run free-threaded.

4.4. Pacotes Alternativos

À parte da distribuição padrão CPython, existem pacotes modificados incluindo funcionalidades adicionais. A seguir está uma lista de versões populares e seus recursos chave:

ActivePython

Instalador com compatibilidade multi-plataforma, documentação, PyWin32

Anaconda

Módulos científicos populares (como o numpy, scipy e pandas) e o gerenciador de pacotes conda.

Enthought Deployment Manager

“A próxima geração de ambiente Python e gerenciador de pacotes”.

Anteriormente, a Enthought fornecia Canopy, mas este chegou ao fim de vida em 2016.

WinPython

Distribuição específica do Windows com pacotes científicos pré-construídos e ferramentas para construir pacotes.

Note que esses pacotes podem não incluir as últimas versões do Python ou outras bibliotecas, e não são mantidos ou suportados pelo time do núcleo do Python.

4.5. Versões do Windows suportadas

As specified in PEP 11, a Python release only supports a Windows platform while Microsoft considers the platform under extended support. This means that Python 3.16 supports Windows 10 and newer. If you require Windows 7 support, install Python 3.8. If you require Windows 8.1 support, install Python 3.12.

4.6. Removendo a limitação de MAX_PATH

O Windows historicamente tem limitado os comprimentos dos caminhos de arquivos em 260 caracteres. Isso significava que caminhos maiores que isso não seriam resolvidos e resultariam em erros.

Nas últimas versões do Windows, essa limitação pode ser expandida para mais de 32.000 caracteres. Seu administrador irá precisar ativar a política de grupo “Enable Win32 long paths”, ou definir LongPathsEnabled para 1 na chave de registro HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem.

Isso permite que a função open(), o módulo os e a maior parte das outras funcionalidades de caminho aceitem e retornem caminhos maiores que 260 caracteres quando usando strings.

Após alterar a opção acima e reiniciar, nenhuma configuração adicional é necessária.

4.7. Modo UTF-8

Adicionado na versão 3.7.

Alterado na versão 3.15: Python UTF-8 mode is now enabled by default (PEP 686).

Windows still uses legacy encodings for the system encoding (the ANSI Code Page). When the Python UTF-8 Mode is disabled, Python uses the ANSI Code Page as the default encoding of text files, as returned by locale.getencoding().

Isso pode causar problemas, porque o UTF-8 é amplamente usado na Internet e na maioria dos sistemas Unix, incluindo o WSL (Subsistema Windows para Linux).

The Python UTF-8 Mode, enabled by default, ignores the system encoding and uses UTF-8 as the default text encoding. When the UTF-8 mode is enabled, you can still use the system encoding (the ANSI Code Page) via the “mbcs” codec.

You can disable the Python UTF-8 Mode via the -X utf8=0 command line option, or the PYTHONUTF8=0 environment variable. See PYTHONUTF8 for disabling UTF-8 mode, and Gerenciador de instalação do Python for how to modify environment variables.

Dica

Adding PYTHONUTF8={0,1} to the default environment variables will affect all Python 3.7+ applications on your system. If you have any Python 3.7+ applications which rely on the legacy system encoding, it is recommended to set the environment variable temporarily or use the -X utf8 command line option.

Nota

Mesmo quando o modo UTF-8 está desativado, o Python usa o UTF-8 por padrão no Windows para:

• E/S do console, incluindo E/S padrão (consulte PEP 528 para detalhes).

• A codificação do sistema de arquivos (veja a PEP 529 para detalhes).

4.8. Encontrando módulos

Estas notas complementam a descrição em A inicialização do caminho de pesquisa de módulos sys.path com notas detalhadas do Windows.

Quando nenhum arquivo ._pth é encontrado, assim é como sys.path é populado no Windows:

• Uma entrada em branco é adicionada ao início, que corresponde ao diretório atual.

• If the environment variable PYTHONPATH exists, as described in Variáveis de ambiente, its entries are added next. Note that on Windows, paths in this variable must be separated by semicolons, to distinguish them from the colon used in drive identifiers (such as C:\).

• “Caminhos da aplicação” adicionais podem ser adicionados ao registro como subchaves de \SOFTWARE\Python\PythonCore{version}\PythonPath sob ambas HKEY_CURRENT_USER e HKEY_LOCAL_MACHINE. Subchaves que possuem string de caminhos delimitados por ponto e vírgula como seu valor padrão farão com que cada caminho seja adicionado ao sys.path. (Note que todos os instaladores conhecidos usam apenas HKLM, portanto HKCU está tipicamente vazio.)

• If the environment variable PYTHONHOME is set, it is assumed as “Python Home”. Otherwise, the path of the main Python executable is used to locate a “landmark file” (either Lib\os.py or pythonXY.zip) to deduce the “Python Home”. If a Python home is found, the relevant sub-directories added to sys.path (such as Lib and plat-win) are based on that folder. Otherwise, the core Python path is constructed from the PythonPath stored in the registry.

• If the Python Home cannot be located, no PYTHONPATH is specified in the environment, and no registry entries can be found, a default path with relative entries is used (for example, .\Lib;.\plat-win).

Se um arquivo pyvenv.cfg for encontrado juntamente com o principal executável ou no diretório um nível acima do executável, as seguintes variações se aplicam:

• Se home é um caminho absoluto e PYTHONHOME não está definido, o caminho é usado ao invés do caminho ao principal executável quando deduzindo a localização do Home.

O resultado final de tudo isso é:

• Quando executando python.exe, ou qualquer outro .exe no diretório principal do Python (ou uma versão instalada, ou diretamente do diretório PCbuild), o caminho núcleo é deduzido, e os caminhos núcleo no registro são ignorados. Outros “caminhos da aplicação” no registro são sempre lidos.

• When Python is hosted in another .exe (for example, in a different directory or embedded via COM), the “Python Home” will not be deduced, so the core path from the registry is used. Other “application paths” in the registry are always read.

• If Python can’t find its home and there are no registry values (frozen .exe, some very strange installation setup) you get a path with some default, but relative, paths.

Para aqueles que querem empacotar o Python em suas aplicações ou distribuições, o seguinte conselho irá prevenir conflitos com outras instalações:

• Inclua um arquivo ._pth juntamente do executável contendo os diretórios a serem incluídos. Isso irá ignorar caminhos listados no registro e variáveis de ambiente, e também ignorar site a não ser que import site seja listado.

• If you are loading python3.dll or python316.dll in your own executable, explicitly set PyConfig.module_search_paths before Py_InitializeFromConfig().

• Limpe e/ou sobrescreva PYTHONPATH e defina PYTHONHOME antes de iniciar o python.exe a partir da sua aplicação.

• Se você não puder usar as sugestões anteriores (por exemplo, você é uma distribuição que permite que as pessoas executem o arquivo python.exe diretamente), certifique-se de que o arquivo de referência (Lib\os.py) existe no seu diretório de instalação. (Note que ele não será detectado dentro de um arquivo ZIP, mas um arquivo ZIP corretamente nomeado será detectado ao invés disso.)

Isso irá garantir que seus arquivos em uma instalação global no sistema não terão precedência sobre uma cópia da biblioteca padrão empacotada com a sua aplicação. Caso contrário, seus usuários podem experienciar problemas usando sua aplicação. Note que a primeira sugestão é a melhor, pois as outras podem ainda estar suscetíveis a caminhos não-padrão no registro e no site-packages do usuário.

Alterado na versão 3.6: Add ._pth file support and remove applocal option from pyvenv.cfg.

Alterado na versão 3.6: Adiciona pythonXX.zip como uma possível referência quando diretamente adjacente ao executável.

Descontinuado desde a versão 3.6: Módulos especificados no registro sob Modules (não PythonPath) podem ser importados por importlib.machinery.WindowsRegistryFinder. Este localizador está ativo no Windows no 3.6.0 e anteriores, mas pode precisar ser explicitamente adicionado ao sys.meta_path no futuro.

4.9. Módulos adicionais

Mesmo que o Python tenha como objetivo ser portável através de todas as plataformas, existem recursos que são únicos para o Windows. Alguns módulos, em ambas as bibliotecas padrão e externa, e trechos de código existem para usar esses recursos.

Os módulos padrão específicos para Windows estão documentados em Serviços Específicos do MS Windows.

4.9.1. PyWin32

O módulo PyWin32 de Mark Hammond é uma coleção de módulos para suporte avançado específico para Windows. Isso inclui utilitários para:

• Component Object Model (COM)

• Chamadas à API Win32

• Registro

• Log de Eventos

• Interfaces de usuário Microsoft Foundation Classes (MFC)

PythonWin é uma aplicação MFC de exemplo enviada com o PyWin32. É uma IDE embutível com um depurador embutido.

Ver também

Win32 How Do I…?

por Tim Golden

Python e COM

by David and Paul Boddie

4.9.2. cx_Freeze

cx_Freeze encapsula scripts Python em programas executáveis do Windows (arquivos *.exe). Quando você tiver feito isso, você pode distribuir sua aplicação sem solicitar que os seus usuários instalem o Python.

4.10. Compilando Python no Windows

Se você quer compilar o CPython por conta própria, a primeira coisa que você precisa ter é a fonte. Você pode fazer o download tanto da fonte da última versão quanto pegar um novo checkout.

A árvore de fontes contém uma solução de construção e arquivos de projeto para o Microsoft Visual Studio, que é o compilador usado para construir as versões do Python oficiais. Esses arquivos estão no diretório PCbuild.

Confira o PCbuild/readme.txt para informações gerais sobre o processo de construção.

Para módulos de extensão, consulte Construindo Extensões C e C++ no Windows.