O módulo sysconfig expõe informações sobre a instalação atual do Python: diretórios de bibliotecas, headers, scripts, dados, variáveis usadas na compilação, plataforma, schemes de instalação e sufixos de extensões. Ele é útil para ferramentas de build, instaladores, diagnósticos de ambiente, empacotamento e integração com código nativo.
Aplicações comuns raramente precisam montar caminhos de instalação manualmente. Para localizar um pacote importado, use importlib; para recursos de um pacote, use importlib.resources; para instalar dependências, use ferramentas de packaging. sysconfig entra em cena quando o objetivo é compreender ou automatizar detalhes da própria instalação do Python.
Informações do ambiente atual
As funções consultam o interpretador que está executando o script. Isso importa quando existem vários Pythons, ambientes virtuais, builds debug, instalações de sistema e distribuições personalizadas.
import sys
import sysconfig
print(sys.executable)
print(sysconfig.get_platform())
print(sysconfig.get_python_version())
Registre o executável junto com os resultados para evitar diagnosticar o ambiente errado.
Schemes de instalação
Um installation scheme é um conjunto de nomes de caminhos usados para instalar diferentes categorias de arquivos.
import sysconfig
print(sysconfig.get_scheme_names())
Os nomes variam por plataforma e distribuição. Não codifique uma lista fixa em uma ferramenta multiplataforma.
Nomes de caminhos
get_path_names() informa as categorias conhecidas, como stdlib, platstdlib, purelib, platlib, include, platinclude, scripts e data.
print(sysconfig.get_path_names())
Cada categoria possui um significado de packaging e pode apontar para o mesmo diretório em determinados ambientes.
stdlib e platstdlib
stdlib aponta para a biblioteca padrão independente da plataforma dentro daquela instalação. platstdlib representa a parte dependente de plataforma.
Não use esses caminhos para modificar arquivos do Python em runtime. Instalações de sistema podem ser somente leitura ou gerenciadas pelo sistema operacional.
purelib e platlib
purelib é o destino típico de pacotes Python puros. platlib é usado por pacotes com componentes dependentes da plataforma.
print(sysconfig.get_path("purelib"))
print(sysconfig.get_path("platlib"))
Em algumas instalações, os dois valores são iguais; em outras, diferem.
include e platinclude
Esses caminhos contêm headers necessários para compilar extensões C ou integrar o runtime.
include = sysconfig.get_path("include")
platinclude = sysconfig.get_path("platinclude")
Uma build tool deve verificar a existência do diretório e não presumir que o pacote de desenvolvimento está instalado.
scripts
O caminho scripts indica onde entry points e scripts são instalados para o scheme escolhido.
Não concatene esse diretório ao PATH do usuário automaticamente sem consentimento. Ferramentas devem informar a localização e oferecer instruções claras.
data
A categoria data funciona como base para arquivos gerais de instalação. Seu significado concreto depende do scheme e da ferramenta de packaging.
Recursos internos de um pacote não devem ser localizados manualmente a partir desse valor; use importlib.resources.
get_paths
get_paths() devolve todos os caminhos de um scheme.
caminhos = sysconfig.get_paths()
for nome, caminho in sorted(caminhos.items()):
print(f"{nome}: {caminho}")
O resultado é apropriado para diagnóstico e build, mas não significa que todos os diretórios existam ou sejam graváveis.
Escolha um scheme
As funções aceitam o nome de um scheme.
caminhos = sysconfig.get_paths(scheme="posix_prefix")
Verifique se o scheme existe em get_scheme_names() antes de usá-lo. Nomes específicos de POSIX não funcionam universalmente no Windows.
Variáveis de expansão
Os templates de caminhos são expandidos com variáveis de configuração. É possível fornecer um mapping vars para simular outro prefixo.
caminhos = sysconfig.get_paths(
vars={"base": "/opt/app", "platbase": "/opt/app"}
)
Simulação não garante que o resultado corresponda a uma instalação válida. Use a ferramenta oficial de packaging para instalar.
get_path
get_path(name) é conveniente quando apenas uma categoria importa.
diretorio_scripts = sysconfig.get_path("scripts")
Valide o nome para evitar KeyError ou comportamento incompatível entre versões.
Variáveis de configuração
get_config_vars() retorna valores usados para construir e configurar o interpretador.
variaveis = sysconfig.get_config_vars()
print(variaveis.get("CC"))
print(variaveis.get("CFLAGS"))
print(variaveis.get("EXT_SUFFIX"))
Os valores são específicos da instalação e podem ser strings, números ou None.
get_config_var
Para consultar uma variável, use get_config_var(name).
sufixo = sysconfig.get_config_var("EXT_SUFFIX")
Não presuma que toda variável existe em todas as plataformas. Trate None.
Compilador e flags
Variáveis como CC, CXX, CFLAGS, LDFLAGS e bibliotecas ajudam ferramentas nativas a reproduzir opções compatíveis.
Não passe strings dessas variáveis diretamente a um shell com entrada adicional não confiável. Faça parsing controlado e use subprocessos com argumentos em lista.
EXT_SUFFIX
EXT_SUFFIX informa o sufixo esperado para extensões compiladas do Python atual.
print(sysconfig.get_config_var("EXT_SUFFIX"))
O valor pode incluir ABI, arquitetura e extensão compartilhada. Não substitua por .so ou .pyd fixos.
SOABI
SOABI identifica aspectos da ABI usados em nomes de extensões.
Uma ferramenta não deve concluir compatibilidade total apenas porque SOABI coincide. Sistema operacional, arquitetura, bibliotecas e versão também importam.
Py_ENABLE_SHARED e bibliotecas
Variáveis de build podem indicar se o Python usa uma biblioteca compartilhada e como ela é nomeada.
Distribuições personalizadas podem alterar esses valores. Para embedding ou linking, teste no ambiente alvo.
get_platform
get_platform() devolve uma string usada para identificar a plataforma em contextos de build.
plataforma = sysconfig.get_platform()
Ela não é um identificador de segurança nem substitui detecção de capacidade. Para comportamento condicional, teste a feature necessária.
get_python_version
A função retorna a versão curta no formato principal.secundária usada nos caminhos de instalação.
Para versão completa, implementação e build, combine com sys.version_info e platform.python_implementation().
Ambientes virtuais
Dentro de um virtual environment, alguns caminhos refletem o ambiente, enquanto informações de build continuam ligadas ao interpretador base.
import sys
print(sys.prefix)
print(sys.base_prefix)
Teste explicitamente em venv. Não presuma que todos os caminhos começam em sys.prefix.
Instalações de sistema
Distribuições Linux podem modificar schemes para integrar Python ao gerenciador de pacotes. Instalar manualmente em diretórios de sistema pode quebrar o ambiente.
Use ambientes virtuais ou a ferramenta recomendada pela distribuição.
Windows
Windows usa schemes e separações diferentes de POSIX. Scripts podem terminar em formatos específicos e extensões usam .pyd com tags de ABI.
Teste caminhos com espaços e caracteres Unicode. Passe argumentos como listas ao compilador.
macOS
Builds framework, universal binaries e arquiteturas diferentes podem alterar paths e flags.
Não copie automaticamente configuração de uma máquina Intel para Apple Silicon ou vice-versa.
Cross compilation
sysconfig descreve principalmente o Python em execução. Em cross compilation, o host e o target são diferentes.
Use arquivos de configuração e ferramentas da cadeia de build do projeto. Não trate os valores do Python host como target.
Ferramentas de diagnóstico
O módulo pode ser executado pela linha de comando para mostrar informações da instalação, conforme a versão.
Em relatórios de suporte, capture o output junto com python -m pip --version, executável e variáveis relevantes, sem incluir segredos do ambiente.
Packaging moderno
Build backends e instaladores modernos já usam as abstrações corretas. Uma aplicação não deveria copiar arquivos para purelib manualmente.
Use pyproject.toml, wheels e ferramentas de instalação. sysconfig é fonte de informação, não um substituto do packaging.
Headers e extensões C
Um build script nativo pode consultar include paths e flags, mas deve preferir padrões suportados por setuptools, Meson, CMake ou o backend escolhido.
Isso facilita wheels e isolamento de build.
Permissões
Um caminho retornado pode ser somente leitura. Verifique permissões antes de gravar e não solicite elevação automaticamente.
Falha de permissão deve produzir uma mensagem que recomende venv, não chmod 777.
Normalização de caminhos
Use pathlib.Path para trabalhar com o texto retornado.
from pathlib import Path
include = Path(sysconfig.get_path("include"))
if not include.is_dir():
raise RuntimeError("headers do Python não encontrados")
Não resolva symlinks sem necessidade, pois o layout da instalação pode depender deles.
Cache dos valores
Os resultados são estáveis durante a execução normal do processo. Uma ferramenta pode armazená-los localmente, mas não deve reutilizar o cache em outro interpretador.
Inclua sys.executable e versão na chave do cache.
Segurança
Variáveis como compilador e flags vêm da configuração do ambiente. Em ambientes comprometidos, podem apontar para executáveis inesperados.
Ferramentas de build devem operar em isolamento, registrar comandos e evitar combinar esses valores com entrada hostil em uma shell.
Testes
Teste em Windows, Linux e macOS, em venv e instalação global, com Python debug quando relevante, paths com espaços, headers ausentes e diretórios sem permissão.
Não faça assertions de caminhos absolutos fixos. Verifique propriedades e categorias.
Erros comuns
Os erros mais frequentes são codificar site-packages manualmente, confundir purelib e platlib, presumir que todos os paths existem, gravar em instalação de sistema, usar valores do host em cross compilation, fixar .so, ignorar venv e executar flags por shell sem parsing.
Conclusão
sysconfig é a fonte oficial para paths, schemes e variáveis de build do Python em execução. Use-o para diagnóstico e integração nativa, sempre considerando plataforma, ambiente virtual, permissões e compatibilidade.
Para instalar pacotes, use ferramentas de packaging em vez de copiar arquivos manualmente. Consulte a documentação oficial de sysconfig e o guia sobre contextlib no Python para gerenciar recursos de build.
