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.

Uma vez encontrados, prefix e exec_prefix estão disponíveis em sys.prefix e sys.exec_prefix, respectivamente.

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.

Ambientes virtuais

Se Python for executado em um ambiente virtual (conforme descrito em Ambientes virtuais e pacotes), então prefix e exec_prefix são específicos para o ambiente virtual.

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 prefix e exec_prefix.

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. Alternativamente, o Py_SetPath() mais antigo pode ser usado para ignorar a inicialização do caminho de pesquisa de módulos.

Ver também