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.

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-codeyclaude-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=optionalde tu comando (pnpm:--no-optional, Yarn:--ignore-optional). - Busca
optional=falseen tu.npmrc. Probé esta: conoptional=falseen el.npmrcde un proyecto, un simplenpm install @anthropic-ai/claude-codeinstaló solo la carpetaclaude-code, ynpm config get omitimprimió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 ajusteallow-scripts, las instalaciones de proyecto iniciadas por una herramientanpxo un scriptnpm runpueden fallar conEALLOWSCRIPTS. Ejecuta antesnpm config get allow-scriptsy anota lo que liste, porque el siguiente comando reemplaza todo el valor. Luego ejecutanpm config set "allow-scripts=@anthropic-ai/claude-code" --location=usery reinstala. Si falla conEACCES, la documentación indica usar el instalador nativo en lugar desudo.
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 claudedeberí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=falseen.npmrc,install.cjs,cli-wrapper.cjs, instalación normal. - No probado: npm 12, pnpm, Yarn, macOS o Windows, espejos corporativos.