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.base_prefix e sys.base_exec_prefix, respectivamente.

Se PYTHONHOME não estiver definido e um arquivo pyvenv.cfg for encontrado ao lado do executável principal ou em seu diretório pai, sys.prefix e sys.exec_prefix serão definidos para o diretório que contém pyvenv.cfg; caso contrário, serão definidos com o mesmo valor que sys.base_prefix e sys.base_exec_prefix, respectivamente. Isso é usado por Ambientes virtuais.

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 e sys.exec_prefix agora são definidos para o diretório pyvenv.cfg durante a inicialização do caminho. Isso era feito anteriormente por site e, portanto, afetado por -S.

Ambientes virtuais

Ambientes virtuais colocam um arquivo pyvenv.cfg em seu prefixo, o que faz com que sys.prefix e sys.exec_prefix apontem para eles, em vez da instalação base.

Os valores prefix e exec_prefix da instalação base estão disponíveis em sys.base_prefix e sys.base_exec_prefix.

Além de ser usado como um marcador para identificar ambientes virtuais, pyvenv.cfg também pode ser usado para configurar a inicialização do site. Consulte a documentação de ambientes virtuais do site.

Nota

PYTHONHOME substitui a detecção pyvenv.cfg.

Nota

Existem outras maneiras de implementar “ambientes virtuais”. Esta documentação menciona implementações baseadas no mecanismo pyvenv.cfg, como venv. A maioria das implementações de ambientes virtuais segue o modelo definido por venv, mas pode haver implementações exóticas que divergem dele.

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