A inicialização do caminho de pesquisa de módulos sys.path

Um caminho de pesquisa de módulos é inicializado quando o Python é iniciado. Este caminho de pesquisa de módulos pode ser acessado em sys.path.

A primeira entrada no caminho de pesquisa de módulos é o diretório que contém o script de entrada, se houver. Caso contrário, a primeira entrada é o diretório atual, que é o caso ao executar o console interativo, um comando com -c ou um módulo com -m.

A variável de ambiente PYTHONPATH é frequentemente usada para adicionar diretórios ao caminho de pesquisa. Se esta variável de ambiente for encontrada, o conteúdo será adicionado ao caminho de pesquisa de módulos.

Nota

PYTHONPATH afetará todas as versões/ambientes Python instalados. Tenha cuidado ao definir isso em seu perfil do shell ou em variáveis de ambiente globais. O módulo site oferece técnicas mais diferenciadas, conforme mencionado abaixo.

Os próximos itens adicionados são os diretórios contendo módulos padrão do Python, bem como quaisquer módulos de extensão dos quais esses módulos dependem. Módulos de extensão são arquivos .pyd no Windows e arquivos .so em outras plataformas. O diretório com os módulos Python independentes de plataforma é chamado prefix. O diretório com os módulos de extensão é chamado exec_prefix.

A variável de ambiente PYTHONHOME pode ser usada para definir os locais prefix e exec_prefix. Caso contrário, esses diretórios serão encontrados usando o executável Python como ponto de partida e, em seguida, procurando por vários arquivos e diretórios “de referência”. Observe que todos os links simbólicos são seguidos para que o local real do executável do Python seja usado como ponto de partida da pesquisa. O local do executável do Python é chamado home.

Uma vez que home é determinado, o diretório prefix é encontrado procurando primeiro por pythonmajorversionminorversion.zip (python311.zip). No Windows, o arquivo zip é procurado em home e no Unix espera-se que o arquivo esteja em lib. Observe que o local esperado do arquivo zip é adicionado ao caminho de pesquisa de módulos, mesmo que o arquivo não exista. Se nenhum arquivo for encontrado, o Python no Windows continuará a pesquisa por prefix procurando por Lib\os.py. Python no Unix procurará por lib/pythonmajorversion.minorversion/os.py (lib/python3.11/os.py). No Windows, prefix e exec_prefix são iguais, porém em outras plataformas lib/pythonmajorversion.minorversion/lib-dynload (lib/python3.11/lib-dynload) é pesquisado e usado como âncora para exec_prefix. Em algumas plataformas, lib pode ser lib64 ou outro valor, veja sys.platlibdir e PYTHONPLATLIBDIR.

Once found, prefix and exec_prefix are available at sys.base_prefix and sys.base_exec_prefix respectively.

If PYTHONHOME is not set, and a pyvenv.cfg file is found alongside the main executable, or in its parent directory, sys.prefix and sys.exec_prefix get set to the directory containing pyvenv.cfg, otherwise they are set to the same value as sys.base_prefix and sys.base_exec_prefix, respectively. This is used by Virtual Environments.

Finalmente, o módulo site é processado e os diretórios site-packages são adicionados ao caminho de pesquisa de módulos. Uma maneira comum de personalizar o caminho de pesquisa é criar módulos sitecustomize ou usercustomize conforme descrito na documentação do módulo site.

Nota

Certas opções de linha de comando podem afetar ainda mais os cálculos de caminho. Veja -E, -I, -s e -S para mais detalhes.

Alterado na versão 3.14: sys.prefix and sys.exec_prefix are now set to the pyvenv.cfg directory during the path initialization. This was previously done by site, therefore affected by -S.

Virtual Environments

Virtual environments place a pyvenv.cfg file in their prefix, which causes sys.prefix and sys.exec_prefix to point to them, instead of the base installation.

The prefix and exec_prefix values of the base installation are available at sys.base_prefix and sys.base_exec_prefix.

As well as being used as a marker to identify virtual environments, pyvenv.cfg may also be used to configure the site initialization. Please refer to site’s virtual environments documentation.

Nota

PYTHONHOME overrides the pyvenv.cfg detection.

Nota

There are other ways how “virtual environments” could be implemented, this documentation referes implementations based on the pyvenv.cfg mechanism, such as venv. Most virtual environment implementations follow the model set by venv, but there may be exotic implementations that diverge from it.

Arquivos _pth

Para substituir completamente sys.path, crie um arquivo ._pth com o mesmo nome da biblioteca compartilhada ou executável (python._pth ou python311._pth). O caminho da biblioteca compartilhada é sempre conhecido no Windows, mas pode não estar disponível em outras plataformas. No arquivo ._pth, especifique uma linha para cada caminho a ser adicionado a sys.path. O arquivo baseado no nome da biblioteca compartilhada substitui aquele baseado no executável, o que permite que os caminhos sejam restritos para qualquer programa que carregue o tempo de execução, se desejado.

Quando o arquivo existe, todos os registros e variáveis de ambiente são ignorados, o modo isolado é ativado, e site não é importado a menos que uma linha do arquivo especifique import site. Caminhos em branco e linhas começando com # são ignorados. Cada caminho pode ser absoluto ou relativo ao local do arquivo. Instruções de importação diferente de site não são permitidas, e código arbitrário não pode ser especificado.

Note que arquivos .pth (sem o sublinhado no início) serão processados normalmente pelo módulo site quando import site tiver sido especificado.

Python embarcado

Se o Python estiver incorporado em outra aplicação, Py_InitializeFromConfig() e a estrutura PyConfig podem ser usados para inicializar o Python. Os detalhes específicos do caminho estão descritos em Python Path Configuration.

Ver também