Tecnología · GUÍA PRÁCTICA
¿node-gyp no encuentra Python? Demuestra la ruta antes de reinstalar
Rastrea el subproceso real de npm, la copia de node-gyp, el selector de Python y la compatibilidad antes de cambiar el entorno.
«Python funciona en mi terminal» y «node-gyp puede usar ese Python» son afirmaciones distintas. Primero demuestra el subproceso real de npm y la ruta de selección.
Sigue la primera etapa que falla—detección, compatibilidad o herramientas nativas—para que cada cambio sea limitado, verificable y reversible.
Congela el primer fallo y el contexto de instalación
Guarda la salida completa desde el primer gyp ERR! find Python hasta el comando final, junto con el directorio y las versiones. Anota si ocurrió en npm install, npm ci, un script, un contenedor o CI.
Conserva también la ruta del comando del registro. Que python3 funcione en un shell interactivo no demuestra que el subproceso de npm comparta PATH, usuario, entorno o copia de node-gyp.
Demuestra qué Node, npm y node-gyp se ejecutaron
En el contexto fallido registra node -p "process.execPath", las versiones y la ruta de node-gyp mostrada por gyp info. Revisa npm config get node_gyp y el script de instalación; binding.gyp puede activar node-gyp automáticamente.
No supongas que instalar node-gyp globalmente cambió la copia usada por npm. Puede existir una copia interna, una dependencia del proyecto o un shim. El registro real es la autoridad.
Prueba Python en el mismo entorno del subproceso
Desde la misma terminal, capa de contenedor, cuenta de servicio o paso de CI, obtiene la ruta absoluta de Python y muestra sys.executable y sys.version. Compárala con npm_config_python, PYTHON y NODE_GYP_FORCE_PYTHON.
Los selectores oficiales son --python, npm_config_python, PYTHON y NODE_GYP_FORCE_PYTHON. Una ruta forzada incompatible detiene la búsqueda. En Windows usa py --list-paths.
Alinea la versión de Python con node-gyp
Un ejecutable puede existir y ser rechazado por su versión. La documentación actual exige node-gyp 10 o superior para Python 3.12 o posterior. Compara con la versión del registro fallido.
Si se elige primero un Python antiguo, elimina el selector obsoleto o apunta a una ruta compatible. Actualiza solo cuando sepas qué copia cambiará y no instales Python 2 por una respuesta antigua.
Separa la detección del siguiente fallo de compilación
Tras seleccionar Python, repite una vez con registro detallado. Si el primer error pasa a make, MSBuild, compilador, cabeceras, binding.gyp o código nativo, la detección ya quedó resuelta.
En Unix hacen falta make y un compilador C/C++; en Windows, el entorno Visual C++. Electron u otros runtimes pueden exigir sus propias cabeceras. Son ramas separadas.
Aplica un único selector limitado y reversible
Usa --python al invocar node-gyp directamente y npm_config_python en el paso de npm. Emplea PYTHON solo como contrato más amplio y reserva el valor forzado para una ruta compatible verificada.
Elimina valores obsoletos del proyecto, usuario, sistema o CI antes de añadir otro. npm_config_ se convierte en configuración y cada npmrc tiene un alcance distinto. Registra el alcance cambiado.
Verifica el comando original y conserva el retroceso
Repite el comando npm original en el contexto original. Confirma la ruta de Python y la versión de node-gyp, y luego carga o prueba el módulo nativo. Configurar con éxito no basta.
Registra valores anteriores y nuevos, rutas, versiones, alcance y comando de eliminación. Borra los selectores temporales si no deben afectar a otros proyectos.
