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.

Para obter o Python da equipe do CPython, use o Python Install Manager (gerenciador de instalação do Python). Esta é uma ferramenta autônoma que disponibiliza o Python como comandos globais na sua máquina Windows, integra-se ao sistema e suporta atualizações ao longo do tempo. Você pode baixar o Python Install Manager. em python.org/downloads ou pelo aplicativo da Microsoft Store.

Após instalar o Python Install Manager, o comando global python pode ser usado em qualquer terminal para iniciar a versão mais recente do Python. Essa versão pode mudar com o tempo, conforme você adiciona ou remove versões diferentes, e o comando py list mostrará qual é a atual.

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>.

Se os comandos python ou py não estiverem funcionando, consulte a seção Solução de problemas abaixo. Às vezes, são necessárias etapas manuais adicionais para configurar seu 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.

Para instalar o arquivo baixado de python.org, clique duas vezes e selecione “Install” ou execute Add-AppxPackage <caminho para MSIX> no 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.

Ao instalar um ambiente de execução pela primeira vez, você provavelmente será solicitado a adicionar um diretório ao seu PATH. Isso é opcional se você preferir usar o comando py, mas é oferecido para aqueles que preferem que todos os apelidos (como python3.14.exe) estejam disponíveis. O diretório será %LocalAppData%\Python\bin por padrão, mas pode ser personalizado por um administrador. Clique em Iniciar e pesquise “Editar as variáveis de ambiente para sua conta” na página de configurações do sistema para adicionar o caminho.

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.

Se você não conseguir instalar um MSIX no seu contexto, por exemplo, se estiver usando um software de implantação automatizada que não oferece suporte a isso ou se estiver mirando o Windows Server 2019, consulte Instalação avançada abaixo para obter mais informações.

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 ...).

Each of these commands also has a windowed version that avoids creating a console window. These are pyw, pythonw and pywmanager. A python3 command is also included that mimics the python command. It is intended to catch accidental uses of the typical POSIX command on Windows, but is not meant to be widely used or recommended.

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.14 ...
$> py -V:3-arm64 ...

Runtimes from other distributors may require the company to be included as well. It should be separated from the tag by a slash (either / or \), and may be shortened to any prefix of its full value. Specifying the company is optional when it is PythonCore, and specifying the tag is optional (but not the slash) when you want the latest release from a specific company.

$> 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.

When no runtimes are installed, any launch command will try to install the requested version and launch it. However, after any version is installed, only the py exec ... and pymanager exec ... commands will install if the requested version is absent. Other forms of commands will display an error and direct you to use py install first.

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.

Vários formatos são suportados e podem ser passados como a opção --format=<FMT> ou -f <FMT>. Os formatos incluem table (uma visualização de tabela amigável), csv (tabela separada por vírgulas), json (um único blob JSON), jsonl (um blob JSON por resultado), exe (apenas o caminho do executável), prefix (apenas o caminho do prefixo).

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.14

Para compatibilidade com o inicializador antigo, os comandos --list, --list-paths, -0 e -0p (por exemplo, py -0p) foram mantidos. Eles não permitem opções adicionais e produzirão uma saída com o formato antigo.

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.

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.

Passar --update substituirá as instalações existentes se a nova versão for mais recente. Caso contrário, elas serão mantidas. Se nenhuma tag for fornecida com --update, todas as instalações gerenciadas pelo gerenciador de instalação do Python serão atualizadas se versões mais recentes estiverem disponíveis. As atualizações removerão quaisquer modificações feitas na instalação, incluindo pacotes instalados globalmente, mas os ambientes virtuais continuarão funcionando.

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.14.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	A plataforma padrão preferida para iniciar ou instalar. Isso é tratado como um sufixo para a tag especificada, de modo que py -V:3.14 prefere uma instalação para 3.14-64 se existir (e default_platform for -64), mas usará 3.14 se não houver nenhuma instalação marcada.
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.14.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

Se a primeira linha de um arquivo de script começar com #!, ela é conhecida como uma linha “shebang”. Linux e outros sistemas operacionais semelhantes ao Unix têm suporte nativo para essas linhas, que são comumente usadas nesses sistemas para indicar como um script deve ser executado. Os comandos python e py permitem que os mesmos recursos sejam usados com scripts Python no 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.

As linhas Shebang que não correspondem a nenhum dos padrões são tratadas como caminhos executáveis do Windows que são absolutos ou relativos ao diretório que contém o arquivo de script Isso é uma conveniência para scripts exclusivos do Windows, como aqueles gerados por um instalador, pois o comportamento não é compatível com shells de estilo Unix. Esses caminhos podem ser citados e podem incluir vários argumentos, após os quais o caminho para o script e quaisquer argumentos adicionais serão anexados.

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.

Independentemente do método de instalação, os usuários ainda precisarão instalar suas próprias cópias do Python, pois não há como acionar essas instalações sem ser um usuário logado. Ao usar o MSIX, a versão mais recente do Python estará disponível para todos os usuários instalarem sem acesso à rede.

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	Lista separada por vírgulas de tipos de atalhos permitidos (por exemplo, "pep514,start"). Atalhos habilitados ainda podem ser desabilitados por disable_shortcut_kinds.
install.disable_shortcut_kinds	Lista separada por vírgulas de tipos de atalhos a serem excluídos (por exemplo, "pep514,start"). Atalhos desabilitados não são reativados por 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.14t
$> py install 3.14t-arm64
$> py install 3.14t-32

Isso vai instalar e registrar como de costume. Se você não tiver outro ambiente de execução instalado, python iniciará este. Caso contrário, você precisará usar py -V:3.14t ... ou, se tiver adicionado o diretório global de apelidos à sua variável de ambiente PATH, o comando python3.14t.exe.

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 organizational unit, 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. Solução de problemas

If your Python install manager does not seem to be working correctly, please work through these tests and fixes to see if it helps. If not, please 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.14-embed --target=<directory>

Quando extraída, a distribuição embutida é (quase) completamente isolada do sistema do usuário, incluindo variáveis de ambiente, configurações de registro de sistema, e pacotes instalados. A biblioteca padrão está inclusa como arquivos .pyc pré-compilados e otimizados em um ZIP, e python3.dll, python313.dll, python.exe e pythonw.exe estão todos disponíveis. Tcl/tk (incluindo todas as dependências, como a Idle), pip e a documentação do Python não estão inclusos.

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.

Para uso da aplicação, pacotes podem ser instalados em qualquer local já que há uma oportunidade de especificar caminhos de busca antes de inicializar o interpretador. De outra forma, não existem diferenças fundamentais entre usar a distribuição embutida ou a instalação regular.

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.

Juntamente com o diretório tools está o diretório build\native. Ele contém um arquivo de propriedades MSBuild python.props que pode ser usado em um projeto C++ para referenciar a instalação do Python. Incluir as configurações irá automaticamente usar os cabeçalhos e importar as bibliotecas na sua construção de projeto.

As páginas de informação dos pacotes em nuget.org são www.nuget.org/packages/python para a versão 64 bits, www.nuget.org/packages/pythonx86 para a versão 32 bits e www.nuget.org/packages/pythonarm64 para a versão ARM64

4.3.1. Pacotes com threads livres

Adicionado na versão 3.13.

Pacotes contendo binários com threads livres são chamados python-freethreaded para a versão de 64 bits, pythonx86-freethreaded para a versão de 32 bits e pythonarm64-freethreaded para a versão ARM64. Esses dois pacotes contêm os pontos de entrada python3.13t.exe e python.exe, os quais são executados com threads livres.

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

Como especificado na PEP 11, uma versão Python suporta apenas uma plataforma Windows enquanto a Microsoft considera a plataforma sob suporte estendido. Isso significa que o Python 3.16 suporta Windows 10 ou superiores. Se você precisa de suporte ao Windows 7, por favor instale o Python 3.8. Se você precisa de suporte ao Windows 8.1, por favor instale o 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).

O Windows ainda usa codificações legadas para a codificação do sistema (a Página de Código ANSI). O Python usa-o para a codificação padrão de arquivos de texto (por exemplo, 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, can help by changing the default text encoding to UTF-8. 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.

• Se a variável de ambiente PYTHONPATH existe, como descrito em Variáveis de ambiente, suas entradas são adicionadas em seguida. Note que no Windows, caminhos nessa variável devem ser separados por ponto e vírgula, para distinguir eles dos dois pontos usados nos identificadores de drivers (C:\ etc.).

• “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.)

• Se a variável de ambiente PYTHONHOME está definida, ela é presumida como “Python Home”. Caso contrário, o caminho do principal executável do Python é usado para localizar um “arquivo de referência” (ou Lib\os.py ou pythonXY.zip) para deduzir o “Python Home”. Se um Python Home é encontrado, os subdiretórios relevantes adicionados ao sys.path (Lib, plat-win, etc) são baseados naquela pasta. Se não, o caminho núcleo do Python é construído a partir do PythonPath armazenado no registro.

• Se o Python Home não puder ser localizado, nenhum PYTHONPATH está especificado no ambiente, e nenhuma entrada de registro pôde ser encontrada, um caminho padrão com entradas relativas é usado (por exemplo, .\Lib;.\plat-win, etc).

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.

• Quando Python é hospedado em outro .exe (diretório diferente, embutido via COM, etc), o “Python Home” não será deduzido, então o caminho núcleo do registro é usado. Outros “caminhos da aplicação” no registro sempre são lidos.

• Se o Python não puder encontrar seu Home e não existem valores no registro (.exe imutáveis, algumas configurações de instalação bem estranhas) você recebe um caminho com alguns caminhos padrão, porém relativos.

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 sites a não ser que import site seja listado.

• Se você estiver carregando python3.dll ou python37.dll em seu próprio executável, defina explicitamente PyConfig.module_search_paths antes de 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: Adiciona suporte a arquivos ._pth e remove a opção applocal do 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.