O módulo site no Python participa da inicialização do interpretador e prepara caminhos específicos da instalação. Ele adiciona diretórios site-packages a sys.path, processa arquivos .pth, tenta importar sitecustomize e usercustomize e, no modo interativo, ajuda a configurar histórico e autocompletar.
Essas operações explicam por que pacotes instalados ficam importáveis e por que duas execuções do mesmo Python podem apresentar caminhos diferentes. Também representam uma superfície sensível: linhas executáveis em arquivos .pth rodam em toda inicialização, e módulos de customização podem executar código arbitrário antes da aplicação começar.
Importação automática durante o startup
Normalmente, Python importa site automaticamente. A opção -S desativa essa etapa.
python -S -c "import sys; print(sys.path)"Com -S, os diretórios site-specific e alguns builtins auxiliares não são adicionados. Desde Python 3.14, os valores sys.prefix e sys.exec_prefix de ambientes virtuais são configurados antes do módulo site, portanto não dependem mais dessa importação.
Chamar site.main() explicitamente
Se o interpretador iniciou com -S, importar site não aplica automaticamente todas as mudanças. Para solicitar o comportamento usual, chame site.main().
import site
site.main()Evite fazer isso em bibliotecas. Alterar sys.path durante a execução é global e pode surpreender outros componentes. O controle pertence ao entry point da aplicação.
Como os diretórios são construídos
O módulo combina prefixos como sys.prefix e sys.exec_prefix com sufixos específicos da plataforma. Em Unix, um caminho típico é lib/pythonX.Y/site-packages; no Windows, é comum Lib/site-packages.
Builds free-threaded podem incluir o sufixo t na versão do diretório, como python3.13t. Não monte caminhos manualmente com strings. Use as funções do módulo ou sysconfig no Python.
Consultar site-packages globais
getsitepackages() retorna os diretórios globais reconhecidos.
import site
for caminho in site.getsitepackages():
print(caminho)A função pode não existir ou não ser útil em todos os ambientes incorporados. Em aplicações portáveis, trate resultados vazios e prefira o contexto do ambiente virtual atual.
Consultar o user site
getusersitepackages() devolve o diretório de pacotes do usuário.
import site
print(site.getusersitepackages())
print(site.ENABLE_USER_SITE)O fato de existir um caminho não significa que ele foi adicionado a sys.path. Consulte ENABLE_USER_SITE.
Interpretar ENABLE_USER_SITE
A flag possui três estados relevantes:
True: o user site está habilitado e foi adicionado.False: foi desabilitado pelo usuário, geralmente com-souPYTHONNOUSERSITE.None: foi desabilitado por segurança ou pelo administrador.
Não converta o valor simplesmente com bool() quando precisa distinguir política de usuário e bloqueio de segurança.
Desabilitar pacotes do usuário
A opção -s impede a inclusão do user site:
python -s -c "import site; print(site.ENABLE_USER_SITE)"A variável PYTHONNOUSERSITE oferece comportamento semelhante. Serviços, jobs automatizados e ambientes reproduzíveis frequentemente devem desabilitar pacotes pessoais para evitar dependências invisíveis.
USER_BASE e PYTHONUSERBASE
getuserbase() retorna a base usada pelo esquema de instalação do usuário. A variável PYTHONUSERBASE pode substituir o padrão.
import site
print(site.getuserbase())
print(site.USER_BASE)Alterar essa variável modifica onde ferramentas podem instalar scripts e módulos do usuário. Defina-a antes de iniciar Python e documente o valor em pipelines.
Executar python -m site
A interface de linha de comando imprime sys.path, user base, user site e o estado de habilitação.
python -m site
python -m site --user-base
python -m site --user-siteÉ uma ferramenta prática para diagnóstico. Quando as opções de user site são usadas, o código de saída também indica se o diretório está habilitado, desabilitado pelo usuário ou bloqueado por segurança.
Arquivos .pth
Arquivos com extensão .pth dentro de diretórios site são processados em ordem alfabética. Linhas comuns adicionam caminhos existentes a sys.path. Linhas vazias e comentários são ignorados.
# exemplo.pth
/opt/meu_app/libs
/opt/meu_app/pluginsCaminhos inexistentes não são adicionados, e duplicatas são evitadas. O módulo não exige que o item seja diretório; um arquivo existente também pode entrar em sys.path.
Ordem alfabética importa
Como os arquivos .pth são processados por nome, a ordem pode alterar precedência de imports. Um pacote com o mesmo nome em dois locais será encontrado conforme a posição final em sys.path.
Evite depender de nomes artificiais como 00-primeiro.pth sem documentação. Prefira ambientes virtuais limpos e instalações normais.
Linhas executáveis em .pth
Uma linha iniciada por import ou import é executada em toda inicialização.
import meu_hook_de_inicioIsso acontece mesmo quando a aplicação nunca usa o pacote relacionado. A documentação limita intencionalmente o código a uma linha para desencorajar inicializações complexas.
Risco de segurança dos .pth
Quem consegue gravar em um diretório site-packages pode obter execução persistente de código em todos os processos Python daquele ambiente. Proteja permissões, revise pacotes instalados e trate arquivos .pth como executáveis.
Em auditorias, liste esses arquivos e destaque linhas de import:
from pathlib import Path
import site
for diretorio in site.getsitepackages():
for arquivo in Path(diretorio).glob('*.pth'):
print(arquivo)
for linha in arquivo.read_text(errors='replace').splitlines():
if linha.startswith(('import ', 'import\t')):
print(' executa:', linha)Encoding dos arquivos .pth
Desde Python 3.13, o módulo tenta decodificar arquivos .pth primeiro como UTF-8 e depois com o encoding da locale. Use UTF-8 para previsibilidade e evite caracteres desnecessários em caminhos de infraestrutura.
Adicionar um diretório com addsitedir()
addsitedir() adiciona um diretório e processa seus arquivos .pth.
import site
site.addsitedir('/opt/meu_app/site-packages')A operação altera sys.path globalmente e pode executar linhas de import. Não use com caminhos fornecidos por usuários. Em plugins, prefira instalação controlada e reinício do processo.
sitecustomize
Depois dos caminhos, Python tenta importar sitecustomize. Administradores podem usar esse módulo para políticas globais, hooks de auditoria, encoding, logging mínimo ou configuração corporativa.
Se o módulo não existe, o ImportError específico é ignorado. Outras exceções podem causar uma falha misteriosa durante o startup. Mantenha o arquivo pequeno, testado e sem dependências externas frágeis.
usercustomize
Quando o user site está habilitado, Python tenta importar usercustomize do diretório do usuário.
Ele pode personalizar sessões interativas, mas não deve ser usado para dependências essenciais de aplicações. Em produção, desabilitar user site evita que preferências pessoais alterem serviços.
Não imprimir durante startup
Saída em sitecustomize ou usercustomize pode interferir com protocolos, CLIs que esperam JSON e ferramentas que analisam stdout. Em pythonw.exe, a saída pode ser ignorada.
Registre apenas quando explicitamente habilitado e escreva logs em destino apropriado.
Configuração automática de readline
Em modo interativo, sem -S, o módulo configura rlcompleter e histórico quando readline está disponível. O arquivo padrão costuma ser ~/.python_history.
Para entender autocompletar e efeitos de atributos dinâmicos, veja rlcompleter no Python.
Desabilitar o hook interativo
sys.__interactivehook__ controla essa configuração. Uma customização pode removê-lo.
import sys
if hasattr(sys, '__interactivehook__'):
del sys.__interactivehook__Faça isso apenas quando você controla a experiência interativa. Não altere o hook em uma biblioteca importada por terceiros.
Ambientes virtuais e pyvenv.cfg
O arquivo pyvenv.cfg pode definir include-system-site-packages = true. Quando falso, o venv não inclui pacotes globais.
Para projetos reproduzíveis, mantenha o valor falso e instale dependências dentro do ambiente. Pacotes globais podem esconder requisitos ausentes.
Verificar prefixos do venv
import sys
print('prefix:', sys.prefix)
print('base_prefix:', sys.base_prefix)
print('venv:', sys.prefix != sys.base_prefix)Em Python 3.14, esses valores continuam corretos mesmo com -S. Isso melhora diagnósticos de ambientes virtuais minimalistas.
site ou sysconfig?
Use site para entender diretórios ativos, user site e customizações de startup. Use sysconfig para esquemas de instalação e caminhos de build de forma estruturada.
Não extraia regras de plataforma a partir de um único caminho observado na sua máquina.
Diagnosticar import inesperado
Quando um módulo vem do local errado:
import modulo
import sys
print(modulo.__file__)
print('\n'.join(sys.path))Depois, examine arquivos .pth, variáveis PYTHONPATH, user site, venv e customizações. pkgutil no Python ajuda a listar módulos disponíveis.
PYTHONPATH e site
PYTHONPATH é processado na inicialização do caminho antes de várias operações de site. Um valor global pode afetar todos os ambientes Python.
Evite defini-lo permanentemente no sistema. Para projetos, use instalação editável controlada ou configuração do ambiente virtual.
Isolamento com -I
A opção isolada -I ignora variáveis PYTHON* e desabilita o user site, entre outras proteções.
python -I -c "import sys; print(sys.path)"Ela é útil para executar ferramentas administrativas com menos influência do ambiente do usuário, embora pacotes globais e customizações da instalação ainda precisem ser considerados.
Testar sitecustomize com segurança
Use um venv temporário, crie o módulo em seu site-packages e execute um subprocesso.
import subprocess
resultado = subprocess.run(
['.venv/bin/python', '-c', 'print("ok")'],
text=True,
capture_output=True,
check=True,
)
assert resultado.stdout.strip() == 'ok'Teste startup normal, -S, -s, erros e ausência de streams. Não experimente no Python global da máquina.
Auditar diferenças
Compare saídas de:
python -m site
python -s -m site
python -S -c "import sys; print(sys.path)"
python -I -m siteAs diferenças mostram influência do user site, do módulo site e do modo isolado.
Erros frequentes
- Adicionar caminhos de usuário com
addsitedir(). - Colocar lógica complexa em uma linha de
.pth. - Usar
sitecustomizecomo sistema de plugins. - Imprimir em stdout durante o startup.
- Depender de pacotes globais dentro do venv.
- Confundir user site existente com user site habilitado.
- Montar caminhos site-packages manualmente.
Boas práticas
- Use venvs limpos e reproduzíveis.
- Proteja permissões de site-packages.
- Audite linhas executáveis em
.pth. - Mantenha customizações mínimas.
- Desabilite user site em serviços.
- Use sysconfig para caminhos estruturados.
- Teste startup em subprocessos.
Conclusão
O site no Python explica boa parte da configuração automática de imports: diretórios site-packages, arquivos .pth, pacotes do usuário e hooks de customização.
Essa conveniência executa antes da aplicação e exige controle rigoroso. Proteja diretórios, evite lógica complexa e use ambientes virtuais. Consulte a documentação oficial do módulo site e a documentação da inicialização de sys.path.
