Las herramientas de packaging, instaladores, extensiones nativas y utilidades de diagnóstico necesitan saber dónde guarda el Python actual sus bibliotecas, scripts, headers y datos. Esas rutas cambian entre Linux, macOS, Windows, instalaciones del sistema, builds personalizados y entornos virtuales. sysconfig en Python ofrece la API oficial para consultar esta información sin codificar rutas fijas.
El módulo también expone variables utilizadas para compilar el intérprete y extensiones C de terceros, como compiladores, flags, directorios de bibliotecas e información ABI. Esta guía explica esquemas de instalación, purelib, platlib, virtualenvs, identificadores de plataforma, variables de build, headers y diagnóstico por línea de comandos.
El contenido complementa nuestras guías sobre py_compile, compileall, types, importlib.resources y zoneinfo.
Por qué fallan las rutas fijas
Una ruta como /usr/local/lib/python3.14/site-packages puede funcionar en un equipo y fallar en otro. Las distribuciones Linux, Homebrew, pyenv, Microsoft Store, frameworks de macOS, containers y entornos virtuales usan layouts diferentes.
Consulta el intérprete que realmente ejecutará o construirá el código. Sysconfig describe esa instalación concreta.
Listar las rutas de instalación
import sysconfig
rutas = sysconfig.get_paths()
for nombre, ruta in rutas.items():
print(nombre, ruta)El resultado incluye biblioteca estándar, paquetes, scripts, headers y datos. Los valores dependen del esquema activo.
purelib y platlib
purelib es el destino de paquetes Python independientes de la plataforma. platlib recibe componentes específicos, especialmente extensiones compiladas.
print(sysconfig.get_path("purelib"))
print(sysconfig.get_path("platlib"))Algunas instalaciones usan la misma ruta para ambos conceptos. No lo supongas en una herramienta portable.
stdlib y platstdlib
stdlib identifica la biblioteca estándar independiente de la plataforma. platstdlib identifica componentes específicos del sistema.
Estas rutas describen Python; no son directorios generales para configuración, uploads o datos mutables de la aplicación.
Directorio de scripts
scripts = sysconfig.get_path("scripts")Los instaladores colocan entry points y ejecutables en este directorio. En POSIX suele ser bin; en Windows, Scripts.
Una herramienta puede informar la ruta cuando un comando no está en PATH, pero no debería modificar la configuración global del shell sin permiso.
Headers de la API C
include = sysconfig.get_path("include")
platinclude = sysconfig.get_path("platinclude")Estas rutas son importantes para compilar extensiones o embeber Python. Un build personalizado puede separar headers generales y específicos.
Verifica que los archivos existan. Una imagen runtime mínima puede no incluir paquetes de desarrollo.
Esquema predeterminado
esquema = sysconfig.get_default_scheme()
print(esquema)Desde Python 3.11, un intérprete dentro de un entorno virtual normalmente devuelve venv.
Listar esquemas disponibles
for esquema in sysconfig.get_scheme_names():
print(esquema)Entre los nombres habituales aparecen posix_prefix, posix_user, posix_home, nt, nt_user y venv. Los redistribuidores pueden personalizar preferencias.
Elegir un esquema preferido
usuario = sysconfig.get_preferred_scheme("user")
prefijo = sysconfig.get_preferred_scheme("prefix")
home = sysconfig.get_preferred_scheme("home")Prefiere esta API pública a las tablas internas, porque un proveedor del sistema puede separar paquetes gestionados por el SO y por pip.
Consultar un esquema concreto
rutas_usuario = sysconfig.get_paths(
scheme=sysconfig.get_preferred_scheme("user")
)Conocer una ruta no demuestra que el proceso pueda escribir en ella. Comprueba permisos por separado.
Templates y expansión
Los esquemas almacenan plantillas con variables como {base}, {platbase} y {py_version_short}. get_path() las expande por defecto.
template = sysconfig.get_path(
"stdlib",
expand=False,
)La forma sin expandir es útil para estudiar el layout, no para abrirla como ruta real.
Sustituir variables
ruta = sysconfig.get_path(
"purelib",
scheme="posix_prefix",
vars={"base": "/opt/python", "platbase": "/opt/python"},
)Esto puede ayudar en staging y construcción de imágenes. No permitas que entrada externa seleccione un destino arbitrario.
Variables de configuración
variables = sysconfig.get_config_vars()
print(variables.get("CC"))
print(variables.get("LIBDIR"))El diccionario reúne valores del Makefile y de pyconfig.h cuando corresponda. En Windows suele existir un conjunto menor.
El resultado completo puede revelar rutas internas. En soporte, selecciona únicamente las claves necesarias.
Consultar una variable
shared = sysconfig.get_config_var("Py_ENABLE_SHARED")
compilador = sysconfig.get_config_var("CC")Una clave desconocida devuelve None. No la conviertas en la string "None" y la pases a una herramienta de build.
Varias variables
ar, cxx, cflags = sysconfig.get_config_vars(
"AR", "CXX", "CFLAGS"
)La lista conserva el orden de los argumentos. Cualquier elemento puede faltar según la plataforma.
Identificador de plataforma
plataforma = sysconfig.get_platform()
print(plataforma)El valor se usa en directorios de build y distribuciones específicas. Ejemplos son linux-x86_64, win-amd64 y tags de macOS.
No es una descripción amigable. Usa platform para informes humanos.
Versión major.minor
version = sysconfig.get_python_version()El resultado omite el patch. Usa sys.version_info cuando necesites esa precisión.
Detectar una árbol de build
if sysconfig.is_python_build():
print("ejecutando desde el árbol de compilación")Esto interesa a herramientas que participan en la construcción de CPython. Las aplicaciones normales rara vez deberían cambiar lógica de negocio por este valor.
Localizar pyconfig.h
header = sysconfig.get_config_h_filename()El archivo contiene macros de configuración. Puede leerse para diagnóstico o build, pero no debe modificarse en la instalación activa.
Localizar el Makefile
makefile = sysconfig.get_makefile_filename()La disponibilidad varía. Prefiere las funciones de alto nivel a analizar el archivo manualmente.
Analizar config.h
with open(header, encoding="utf-8", errors="surrogateescape") as archivo:
valores = sysconfig.parse_config_h(archivo)La función está diseñada para archivos del estilo config.h, no es un preprocesador C completo.
Entornos virtuales
Dentro de un venv, los paquetes y scripts apuntan al entorno mientras partes de la biblioteca estándar pueden permanecer en la instalación base. No reconstruyas rutas a partir de sys.prefix; consulta sysconfig.
Instalar paquetes
Sysconfig describe destinos usados por instaladores. Una aplicación no debería copiar módulos directamente a site-packages. Usa pip, wheels y backends de build para conservar metadatos y permitir desinstalación.
Extensiones nativas y ABI
Variables como EXT_SUFFIX, SOABI, CC, CFLAGS y LDSHARED ayudan a igualar la configuración del intérprete.
sufijo = sysconfig.get_config_var("EXT_SUFFIX")
soabi = sysconfig.get_config_var("SOABI")No construyas una string de shell con esos valores. Usa una herramienta de build o una lista estructurada de argumentos.
Cross-compilation
El sysconfig del intérprete en ejecución describe principalmente ese intérprete. En compilación cruzada, host y target son diferentes. Usa los datos proporcionados por la toolchain del destino.
No supongas que get_platform() representa el target si lo ejecutas en el host.
Containers mínimos
Una imagen runtime puede no tener compilador, Makefile ni headers aunque sysconfig indique rutas conceptuales. Comprueba existencia antes de abrir o ejecutar.
Separa etapas de build y runtime al compilar wheels nativas.
Interfaz de línea de comandos
python -m sysconfigEl comando muestra plataforma, versión, esquema, rutas y variables. Es útil en CI y soporte. Revisa la salida antes de publicarla, porque puede revelar detalles internos.
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"),
}Recoge solo la información necesaria para el problema actual.
Pruebas portables
Evita afirmar una ruta absoluta concreta. Comprueba tipos, valores no vacíos, relaciones y existencia solo cuando el despliegue lo garantice.
def test_ruta_scripts():
ruta = sysconfig.get_path("scripts")
assert isinstance(ruta, str)
assert rutaEjecuta la matriz en Windows, Linux, macOS y virtualenvs soportados.
Errores frecuentes
- Codificar manualmente site-packages.
- Confundir
purelibyplatlib. - Suponer que toda ruta existe o es escribible.
- Pasar una variable ausente a un comando.
- Copiar paquetes en lugar de usar packaging.
- Ejecutar flags mediante una string de shell insegura.
- Confundir host de build y target.
- Publicar diagnósticos completos con rutas internas.
Buenas prácticas
- Consulta el intérprete que ejecutará el código.
- Usa esquemas preferidos.
- Trata valores
None. - Comprueba existencia y permiso por separado.
- Usa packaging moderno.
- Pasa comandos como argumentos estructurados.
- Prueba virtualenvs y plataformas soportadas.
- Recoge solo diagnóstico necesario.
Conclusión
sysconfig en Python es la fuente oficial para rutas de instalación, esquemas, variables de build, ABI e identificación de plataforma del intérprete activo. Evita suposiciones frágiles en herramientas de packaging, extensiones nativas y diagnósticos.
Usa la información como descripción del entorno, no como autorización para escribir. Combina sysconfig con packaging moderno, comprobaciones de permisos y pruebas multiplataforma. Consulta la documentación oficial de sysconfig y la guía oficial de packaging.
