# 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

- Encontrando módulos para observações detalhadas do Windows.

- Utilizando Python em plataformas Unix para detalhes do Unix.