Ferramentas de empacotamento, instaladores, extensões C e diagnósticos precisam saber onde o Python atual guarda bibliotecas, scripts, headers e dados. Esses caminhos mudam entre Linux, macOS, Windows, instalações de sistema, builds customizados e ambientes virtuais. O módulo sysconfig no Python fornece uma API oficial para consultar essas informações sem codificar caminhos fixos.
Além dos diretórios, ele expõe variáveis usadas na compilação do interpretador e de extensões nativas, como compiladores, flags, diretório de bibliotecas e opções de build. Neste guia você aprenderá a consultar esquemas, diferenciar purelib e platlib, detectar virtualenvs, obter o identificador de plataforma e evitar scripts frágeis.
O conteúdo complementa nossos artigos sobre py_compile, compileall, types, importlib.resources e zoneinfo.
Por que não montar caminhos manualmente
Um caminho como /usr/local/lib/python3.14/site-packages pode funcionar em uma máquina e falhar em outra. Distribuições Linux, Homebrew, pyenv, Windows Store, frameworks do macOS e ambientes virtuais usam layouts diferentes.
Use sysconfig para perguntar ao interpretador em execução qual esquema está ativo.
Listar todos os caminhos
import sysconfig
caminhos = sysconfig.get_paths()
for nome, caminho in caminhos.items():
print(nome, caminho)O resultado inclui diretórios de biblioteca padrão, pacotes, scripts, headers e dados.
purelib e platlib
purelib é o diretório de pacotes Python sem componentes específicos da plataforma. platlib recebe pacotes dependentes da plataforma, como extensões compiladas.
print(sysconfig.get_path("purelib"))
print(sysconfig.get_path("platlib"))Em algumas instalações os dois caminhos são iguais. Não presuma que isso acontece sempre.
stdlib e platstdlib
stdlib contém módulos da biblioteca padrão independentes da plataforma. platstdlib identifica componentes específicos do sistema.
Esses caminhos descrevem a instalação do Python; não são um destino genérico para arquivos da sua aplicação.
Diretório de scripts
scripts = sysconfig.get_path("scripts")Instaladores usam esse caminho para executáveis e entry points. Em Windows costuma ser uma pasta Scripts; em POSIX, normalmente bin.
Não acrescente o caminho ao PATH global silenciosamente. Mostre instruções claras ao usuário.
Headers da C API
include = sysconfig.get_path("include")
platinclude = sysconfig.get_path("platinclude")Esses diretórios são importantes para compilar extensões C e ferramentas que incorporam Python. Builds customizados podem separar headers gerais e específicos da plataforma.
Esquema padrão
esquema = sysconfig.get_default_scheme()
print(esquema)Desde Python 3.11, um interpretador dentro de ambiente virtual normalmente retorna o esquema venv.
Listar esquemas disponíveis
for esquema in sysconfig.get_scheme_names():
print(esquema)Entre os nomes comuns estão posix_prefix, posix_user, nt, nt_user e venv. Redistribuidores podem personalizar preferências.
Escolher esquema por intenção
usuario = sysconfig.get_preferred_scheme("user")
prefixo = sysconfig.get_preferred_scheme("prefix")As chaves aceitas são user, home e prefix. Prefira essa função a detalhes internos, pois distribuições podem ajustar seus layouts.
Consultar um esquema específico
caminhos_usuario = sysconfig.get_paths(
scheme=sysconfig.get_preferred_scheme("user")
)Consultar não concede permissão de escrita. Verifique acesso e políticas do ambiente antes de criar arquivos.
Expansão de variáveis
Os esquemas armazenam templates com variáveis como {base} e {py_version_short}. Por padrão, get_path() expande essas variáveis.
template = sysconfig.get_path(
"stdlib",
expand=False,
)O modo não expandido é útil para estudar ou documentar o esquema, não para abrir diretamente o caminho.
Substituir variáveis de expansão
caminho = sysconfig.get_path(
"purelib",
scheme="posix_prefix",
vars={"base": "/opt/python", "platbase": "/opt/python"},
)Esse recurso ajuda ferramentas de staging e packaging. Valide destinos e não permita que entrada externa escolha diretórios arbitrários.
Variáveis de configuração
variaveis = sysconfig.get_config_vars()
print(variaveis.get("CC"))
print(variaveis.get("LIBDIR"))O dicionário reúne valores do Makefile e de pyconfig.h quando disponíveis. No Windows, o conjunto costuma ser menor.
Consultar variáveis específicas
compartilhado = sysconfig.get_config_var("Py_ENABLE_SHARED")
compilador = sysconfig.get_config_var("CC")Uma chave desconhecida devolve None. Não converta o resultado diretamente para string e trate "None" como configuração real.
Várias variáveis de uma vez
ar, cxx, flags = sysconfig.get_config_vars("AR", "CXX", "CFLAGS")O retorno é uma lista na mesma ordem dos nomes. Valide cada elemento porque alguns podem não existir na plataforma.
Identificador de plataforma
plataforma = sysconfig.get_platform()
print(plataforma)O valor é usado em diretórios de build e distribuições específicas, com exemplos como linux-x86_64, win-amd64 e macosx-15.5-arm64.
Ele não é uma descrição amigável do sistema e não deve substituir o módulo platform em relatórios humanos.
Versão major.minor
versao = sysconfig.get_python_version()
print(versao)O formato contém major e minor, como 3.14, sem patch. Use sys.version_info quando precisar de granularidade maior.
Detectar execução em árvore de build
if sysconfig.is_python_build():
print("Python está rodando a partir da árvore de compilação")Isso interessa a ferramentas que participam da construção do próprio Python. Aplicações comuns raramente precisam alterar comportamento com base nesse valor.
Localizar pyconfig.h
cabecalho = sysconfig.get_config_h_filename()O arquivo contém macros da configuração do interpretador. Leia-o para diagnóstico ou build, mas não o modifique na instalação ativa.
Localizar o Makefile
makefile = sysconfig.get_makefile_filename()Em plataformas sem o mesmo modelo de Makefile, o conteúdo e a disponibilidade variam. Use as funções de variáveis sempre que possível.
Analisar config.h
with open(cabecalho, encoding="utf-8", errors="surrogateescape") as arquivo:
valores = sysconfig.parse_config_h(arquivo)Essa função é voltada a arquivos no estilo config.h. Não a use para analisar headers C arbitrários.
Ambientes virtuais
Dentro de um venv, caminhos e esquema devem apontar para o ambiente, enquanto a biblioteca padrão pode permanecer na instalação base. Não use apenas sys.prefix != sys.base_prefix para reconstruir diretórios manualmente; consulte sysconfig.
Instalação de pacotes
Ferramentas de packaging usam esquemas, mas aplicações não devem copiar módulos diretamente para site-packages. Use pip, build backends e padrões de packaging para manter metadados, dependências e desinstalação.
Extensões nativas
Ao compilar uma extensão, variáveis como EXT_SUFFIX, SOABI, CC, CFLAGS, LDSHARED e caminhos de include ajudam a reproduzir a configuração correta.
sufixo = sysconfig.get_config_var("EXT_SUFFIX")
soabi = sysconfig.get_config_var("SOABI")Evite concatenar uma linha de compilador e executá-la com shell. Use listas de argumentos e ferramentas de build.
Cross-compilation
O sysconfig do interpretador em execução descreve principalmente esse interpretador. Em cross-compilation, host e target podem ser diferentes. Use as informações fornecidas pelo ambiente de build e pela toolchain do destino.
Não presuma que get_platform() representa o target quando você está executando no host.
Containers e imagens mínimas
Uma imagem runtime pode não conter compilador, Makefile completo ou headers, mesmo que sysconfig mostre caminhos conceituais. Verifique existência antes de abrir.
Separe imagem de build e runtime quando compilar extensões.
Interface de linha de comando
python -m sysconfigO comando imprime plataforma, versão, esquema, caminhos e variáveis. É útil em relatórios de suporte, CI e diagnóstico de instalação.
Revise a saída antes de publicá-la, pois pode revelar diretórios internos e nomes da infraestrutura.
Criar um diagnóstico compacto
def diagnostico():
return {
"python": sysconfig.get_python_version(),
"platform": sysconfig.get_platform(),
"scheme": sysconfig.get_default_scheme(),
"purelib": sysconfig.get_path("purelib"),
"scripts": sysconfig.get_path("scripts"),
"soabi": sysconfig.get_config_var("SOABI"),
}Não inclua o dicionário completo de variáveis sem necessidade. Colete apenas dados relevantes ao problema.
Testes
Testes devem evitar afirmar caminhos absolutos específicos. Verifique propriedades, existência quando esperada e consistência entre funções.
def test_caminho_scripts():
caminho = sysconfig.get_path("scripts")
assert isinstance(caminho, str)
assert caminhoExecute a matriz em Windows, Linux, macOS e venv quando o projeto suporta esses ambientes.
Erros frequentes
- Codificar
site-packagesmanualmente. - Confundir
purelibeplatlib. - Presumir que todo caminho existe ou é gravável.
- Usar variável ausente como string.
- Copiar pacotes diretamente em vez de usar packaging.
- Executar flags do compilador através de shell inseguro.
- Confundir plataforma de build e target.
- Publicar diagnóstico completo com caminhos internos.
Boas práticas
- Consulte o interpretador que realmente executará o código.
- Use esquemas preferidos em vez de detalhes internos.
- Trate valores
None. - Verifique existência e permissão separadamente.
- Use ferramentas de packaging para instalações.
- Passe argumentos de build como listas.
- Teste virtualenvs e plataformas suportadas.
- Colete apenas diagnóstico necessário.
Conclusão
O módulo sysconfig no Python é a fonte oficial para caminhos de instalação, esquemas, variáveis de build e identificação de plataforma do interpretador atual. Ele evita suposições frágeis em ferramentas de empacotamento, extensões nativas e diagnósticos.
Use essas informações como descrição do ambiente, não como autorização para escrever em qualquer diretório. Combine sysconfig com packaging moderno, validação de permissões e testes multiplataforma. Consulte a documentação oficial de sysconfig e a documentação oficial de packaging ao criar instaladores e builds.
