El módulo sysconfig expone información sobre la instalación actual de Python: directorios de biblioteca, destinos de paquetes, headers, scripts, datos, variables de compilación, plataforma, schemes de instalación y sufijos de extensiones. Es útil para herramientas de build, instaladores, diagnóstico de entornos, packaging e integración con código nativo.
Las aplicaciones normales rara vez necesitan construir rutas de instalación manualmente. Usa importlib para localizar módulos, importlib.resources para recursos y herramientas de packaging para instalar dependencias. sysconfig corresponde cuando el objetivo es comprender o automatizar detalles de la propia instalación de Python.
El runtime actual
Los resultados describen el intérprete que está ejecutando el script. Esto importa cuando hay varios Pythons, entornos virtuales, builds debug, instalaciones del sistema y distribuciones personalizadas.
import sys
import sysconfig
print(sys.executable)
print(sysconfig.get_platform())
print(sysconfig.get_python_version())
Registra el ejecutable junto con el diagnóstico para no analizar el entorno equivocado.
Schemes de instalación
Un scheme es un conjunto nombrado de templates de rutas para diferentes categorías de archivos.
import sysconfig
print(sysconfig.get_scheme_names())
Los nombres disponibles cambian según plataforma y distribución. No codifiques una lista universal.
Categorías de rutas
get_path_names() muestra categorías como stdlib, platstdlib, purelib, platlib, include, platinclude, scripts y data.
print(sysconfig.get_path_names())
Varias categorías pueden resolver al mismo directorio en una instalación concreta.
stdlib y platstdlib
stdlib identifica la biblioteca estándar independiente del layout de extensiones. platstdlib representa contenido dependiente de plataforma.
No modifiques esos directorios en runtime. Las instalaciones de sistema pueden ser read-only o gestionadas por el package manager.
purelib y platlib
purelib es el destino habitual de paquetes Python puros. platlib se usa para paquetes con componentes dependientes de plataforma.
print(sysconfig.get_path("purelib"))
print(sysconfig.get_path("platlib"))
Pueden ser iguales en una instalación y diferentes en otra.
include y platinclude
Estas categorías localizan headers necesarios para compilar extensiones C o embeber Python.
include = sysconfig.get_path("include")
include_plataforma = sysconfig.get_path("platinclude")
Una herramienta debe verificar que existan. Algunos sistemas requieren un paquete de desarrollo separado.
scripts
La ruta scripts indica dónde se instalan entry points de línea de comandos.
No modifiques el PATH del usuario automáticamente. Informa la ubicación y proporciona instrucciones claras.
data
La categoría data funciona como base para datos generales del scheme.
No la uses para localizar recursos dentro de un paquete importado. Utiliza importlib.resources.
get_paths
get_paths() devuelve todas las rutas expandidas.
rutas = sysconfig.get_paths()
for nombre, ruta in sorted(rutas.items()):
print(f"{nombre}: {ruta}")
Es útil para diagnóstico y build, pero no garantiza que todos los directorios existan o permitan escritura.
Selecciona un scheme
Las funciones aceptan un nombre explícito.
rutas = sysconfig.get_paths(scheme="posix_prefix")
Comprueba get_scheme_names(). Un nombre de POSIX no es portable a Windows.
Variables de templates
Los templates se expanden con variables de configuración. Un mapping vars puede simular otro prefijo.
rutas = sysconfig.get_paths(
vars={"base": "/opt/app", "platbase": "/opt/app"}
)
Una simulación no es necesariamente una instalación válida. Usa packaging para instalar realmente.
get_path
get_path(name) es cómodo cuando solo necesitas una categoría.
directorio_scripts = sysconfig.get_path("scripts")
Valida nombres y maneja diferencias entre versiones.
Variables de configuración
get_config_vars() devuelve valores usados para configurar y compilar el intérprete.
variables = sysconfig.get_config_vars()
print(variables.get("CC"))
print(variables.get("CFLAGS"))
print(variables.get("EXT_SUFFIX"))
Los valores dependen de la instalación y pueden ser strings, números o None.
get_config_var
Usa get_config_var(name) para una sola variable.
sufijo = sysconfig.get_config_var("EXT_SUFFIX")
No supongas que todas existen en todas las plataformas. Maneja None.
Compilador y flags
Variables como CC, CXX, CFLAGS, LDFLAGS y nombres de bibliotecas ayudan a herramientas nativas.
No combines esas strings con entrada no confiable y las envíes a shell. Haz parsing controlado y usa listas de argumentos.
EXT_SUFFIX
EXT_SUFFIX informa el sufijo esperado de extensiones compiladas.
print(sysconfig.get_config_var("EXT_SUFFIX"))
Puede incluir ABI, arquitectura y detalles de librería. No lo reemplaces por .so o .pyd fijos.
SOABI
SOABI identifica información de ABI usada en nombres de extensiones.
Que SOABI coincida no prueba compatibilidad total. Sistema, arquitectura, librerías y build también importan.
Biblioteca compartida
Variables de build indican si Python usa shared library y cómo se llama.
Distribuciones personalizadas pueden cambiar valores. Prueba linking y embedding en el target real.
get_platform
get_platform() devuelve una string usada en contextos de build y packaging.
plataforma = sysconfig.get_platform()
No es identidad de seguridad ni sustituye detección de capacidades.
get_python_version
Devuelve la versión corta principal.secundaria usada en rutas.
Para detalles completos, combínala con sys.version_info y platform.python_implementation().
Entornos virtuales
Dentro de un venv, varias rutas apuntan al entorno mientras información de build continúa ligada al intérprete base.
import sys
print(sys.prefix)
print(sys.base_prefix)
Prueba en un venv real. No asumas que todas las rutas comienzan con sys.prefix.
Instalaciones del sistema
Distribuciones Linux pueden personalizar schemes para su gestor de paquetes. Escribir manualmente en ubicaciones del sistema puede romper el entorno.
Usa entornos virtuales o el método recomendado por la distribución.
Windows
Windows usa schemes distintos de POSIX. Layout de scripts, sufijos de extensiones y tags de ABI siguen sus propias convenciones.
Prueba rutas con espacios y Unicode. Pasa argumentos al compilador como lista.
macOS
Builds framework, universal binaries y arquitecturas pueden alterar rutas y flags.
No copies configuración de Intel a Apple Silicon o al revés sin validación.
Cross compilation
sysconfig describe principalmente el Python que se ejecuta. En cross compilation, host y target son diferentes.
Usa configuración específica del target y la toolchain del proyecto. Los valores del host no son automáticamente válidos.
Diagnóstico
El módulo puede ejecutarse desde línea de comandos para mostrar información, según la versión.
Un informe de soporte debería incluir ejecutable, output relevante y versión de packaging sin exponer secretos.
Packaging moderno
Build backends e instaladores ya usan abstracciones apropiadas. Una aplicación no debería copiar archivos directamente a purelib.
Usa pyproject.toml, wheels e instaladores soportados. sysconfig informa; no reemplaza packaging.
Extensiones C
Un build nativo puede consultar includes y flags, pero debería apoyarse en setuptools, Meson, CMake o el backend elegido.
Esto facilita wheels y aislamiento.
Permisos
Una ruta devuelta puede ser read-only. Comprueba antes de escribir y no solicites elevación automáticamente.
Ante falta de permisos, recomienda venv, no chmod 777.
Manejo de rutas
Convierte el texto en pathlib.Path al operar con filesystem.
from pathlib import Path
include = Path(sysconfig.get_path("include"))
if not include.is_dir():
raise RuntimeError("headers de Python no encontrados")
No resuelvas symlinks sin necesidad; el layout puede depender de ellos.
Cache de resultados
Los valores suelen ser estables durante el proceso. Puedes cachearlos localmente, pero no reutilizarlos para otro intérprete.
Incluye sys.executable y versión en la clave.
Seguridad
Comandos del compilador y flags provienen de la configuración. En un entorno comprometido pueden apuntar a ejecutables inesperados.
Las herramientas de build deben aislarse, registrar comandos y evitar shell con entrada hostil.
Pruebas
Prueba Windows, Linux, macOS, venv, instalación global, paths con espacios, headers ausentes y directorios read-only.
No hagas assertions con rutas absolutas fijas. Verifica propiedades.
Errores comunes
Los fallos frecuentes son codificar site-packages, confundir purelib y platlib, asumir que todos los directorios existen, escribir en Python de sistema, usar valores del host en cross compilation, fijar .so, ignorar venv y ejecutar flags mediante shell.
Conclusión
sysconfig es la fuente oficial de rutas, schemes y variables de build del runtime actual. Úsalo para diagnóstico e integración nativa considerando plataforma, venv, permisos y compatibilidad.
Usa herramientas de packaging en vez de copiar archivos manualmente. Consulta la documentación oficial de sysconfig y contextlib en Python para gestión de recursos.
