Todos los artículos

Claude Code «claude native binary not installed»: 2 causas y soluciones probadas (2026)

«claude native binary not installed» indica que la instalación de npm quedó a medias: o se omitió postinstall o nunca se descargó el paquete de la plataforma. Mira primero node_modules/@anthropic-ai y luego ejecuta install.cjs o reinstala. Probado con npm 11; lo de npm 12 viene de la documentación.

Claude native binary not installed: caja de arcilla vacía con un engranaje suelto y una pequeña terminal de arcilla
También disponible en中文English

Respuesta corta: Error: claude native binary not installed. significa que la instalación de npm terminó solo a medias. El comando claude de tu PATH sigue siendo un pequeño script de relleno, porque el paquete de la plataforma nunca se descargó (--omit=optional, o optional=false en .npmrc) o el paso postinstall que copia el binario real no se ejecutó (--ignore-scripts, o los valores por defecto de npm 12). Cuál sea tu caso decide la solución. Reproduje ambos con Claude Code 2.1.319 y npm 11.21.1 en Linux y probé las soluciones. La parte de npm 12 viene de la documentación de Anthropic, porque no tenía npm 12.

Qué es el script de relleno

El paquete npm @anthropic-ai/claude-code es pequeño. Según la página de solución de problemas de instalación de Anthropic, el programa real es una dependencia opcional por plataforma, como @anthropic-ai/claude-code-linux-x64, y un paso postinstall lo copia a su sitio. Hasta que pasen las dos cosas, claude es un relleno que imprime esto:

Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).

Run the postinstall manually (adjust path for local vs global install):
  node node_modules/@anthropic-ai/claude-code/install.cjs

Or reinstall without --ignore-scripts / --omit=optional.

Vi exactamente este texto en las dos reproducciones de abajo. En Windows, según la documentación, el relleno es un script guardado como claude.exe, así que PowerShell y CMD dicen que no pueden ejecutar el archivo en lugar de imprimir este mensaje.

Paso 1: averigua en qué caso estás

Mira dentro de la carpeta donde instaló npm (npm root -g para una instalación global, o el node_modules local):

ls node_modules/@anthropic-ai/
  • Ves claude-code y claude-code-linux-x64 (o el nombre de tu plataforma): el binario se descargó y solo se omitió el paso de copia. Es el caso de --ignore-scripts.
  • Ves solo claude-code: el paquete de la plataforma nunca se descargó. Es el caso de --omit=optional.

Esto obtuve: con --ignore-scripts estaban las dos carpetas, y tras install.cjs el archivo bin/claude.exe era un binario real de unos 340 MB. Con --omit=optional solo existía claude-code y bin/claude.exe era un relleno de 500 bytes.

Caso A: se omitieron los scripts (el paquete de plataforma está)

Ejecuta el postinstall a mano, como dice el mensaje:

node node_modules/@anthropic-ai/claude-code/install.cjs
claude --version

Lo probé tras npm install @anthropic-ai/claude-code --ignore-scripts. Antes de arreglarlo claude imprimía el error. Después, claude --version imprimió 2.1.319 (Claude Code).

Si no puedes ejecutar el postinstall, la documentación menciona una alternativa que encuentra el paquete descargado y lo inicia, con un proceso Node extra en cada arranque:

node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs --version

Eso también funcionó en mi prueba (imprimió 2.1.319 (Claude Code)).

Caso B: se omitieron las dependencias opcionales (falta el paquete de plataforma)

Volver a ejecutar install.cjs no ayuda, porque no hay binario que copiar. Lo probé. El script dijo:

[@anthropic-ai/claude-code postinstall] Native package "@anthropic-ai/claude-code-linux-x64" not found.
  This happens with --omit=optional or when the download failed; re-run the install to fetch it.

y el envoltorio dijo Could not find native binary package "@anthropic-ai/claude-code-linux-x64". La solución es encontrar qué desactiva las dependencias opcionales y reinstalar.

  • Quita --omit=optional de tu comando (pnpm: --no-optional, Yarn: --ignore-optional).
  • Busca optional=false en tu .npmrc. Probé esta: con optional=false en el .npmrc de un proyecto, un simple npm install @anthropic-ai/claude-code instaló solo la carpeta claude-code, y npm config get omit imprimió optional. npm mostró además una advertencia de configuración que sugiere usar --omit=optional.
  • Revisa tu registro. La documentación de Anthropic dice que un espejo npm corporativo debe tener los ocho paquetes de plataforma además del principal.

Luego reinstala (npm install -g @anthropic-ai/claude-code para una instalación global) y ejecuta claude --version.

npm 12 y el postinstall omitido (según la documentación oficial)

No pude probar esta parte. La documentación dice que npm 12 termina la instalación sin ejecutar el paso postinstall salvo que tu configuración lo permita. Comprueba con npm --version; si empieza por 12, la documentación da dos salidas:

  • Cambiar al instalador nativo y desinstalar la copia de npm. Las actualizaciones ya no pasan por npm, así que el error no vuelve.
  • Seguir con npm: si tu versión es 12.0.x, primero actualiza a 12.1 o posterior (por ejemplo npm install -g npm@latest); una vez guardado el ajuste allow-scripts, las instalaciones de proyecto iniciadas por una herramienta npx o un script npm run pueden fallar con EALLOWSCRIPTS. Ejecuta antes npm config get allow-scripts y anota lo que liste, porque el siguiente comando reemplaza todo el valor. Luego ejecuta npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user y reinstala. Si falla con EACCES, la documentación indica usar el instalador nativo en lugar de sudo.

En mi npm 11.21.1, una instalación normal mostró una advertencia de que el script postinstall de Claude Code «not yet covered by allowScripts», y aun así la instalación funcionó y dejó en su sitio un binario de 340 MB. No des por hecho que seguirá así en npm 12.

Si el error sigue

  • Asegúrate de que ningún relleno antiguo va primero en tu PATH: type -a claude debería listar solo la copia que quieres.
  • La documentación lista binarios precompilados solo para macOS, Linux (glibc y musl) y Windows en x64 y arm64. Otras plataformas, incluida FreeBSD, no son compatibles.
  • Para una instalación limpia sin npm, sigue la guía para instalar Claude Code. Otros mensajes de Claude Code están en la lista de errores.

Preguntas frecuentes

¿El error se debe a que Claude Code está roto?

No. El programa está bien. La instalación quedó incompleta.

¿sudo npm install -g lo arregla?

Por sí solo no. La causa es un paso omitido, no los permisos, y la documentación aconseja no repetirlo con sudo tras un error EACCES.

¿Cuál es la forma más simple de evitarlo para siempre?

La documentación recomienda el instalador nativo: no pasa por npm, así que no hay un paso postinstall que omitir. Las actualizaciones tampoco usan npm.

Fuentes y notas de prueba

  • Documentación de Anthropic: solución de problemas de instalación, sección «Native binary not found after npm install» (code.claude.com/docs/en/troubleshoot-install).
  • Probado por mí: Claude Code 2.1.319 y npm 11.21.1 en Linux x64: --ignore-scripts, --omit=optional, optional=false en .npmrc, install.cjs, cli-wrapper.cjs, instalación normal.
  • No probado: npm 12, pnpm, Yarn, macOS o Windows, espejos corporativos.

Deja una idea

Tu dirección de correo no se publicará.